chore(meta): Version bump
[plugin.video.netflix.git] / resources / lib / NetflixSession.py
1 #!/usr/bin/env python
2 # -*- coding: utf-8 -*-
3 # Module: NetflixSession
4 # Created on: 13.01.2017
5
6 import os
7 import json
8 from requests import session, cookies
9 from urllib import quote
10 from time import time
11 from base64 import urlsafe_b64encode
12 from bs4 import BeautifulSoup, SoupStrainer
13 from utils import noop
14 try:
15    import cPickle as pickle
16 except:
17    import pickle
18
19 class NetflixSession:
20     """Helps with login/session management of Netflix users & API data fetching"""
21
22     base_url = 'https://www.netflix.com'
23     """str: Secure Netflix url"""
24
25     urls = {
26         'login': '/login',
27         'browse': '/profiles/manage',
28         'video_list_ids': '/preflight',
29         'shakti': '/pathEvaluator',
30         'profiles':  '/profiles/manage',
31         'switch_profiles': '/profiles/switch',
32         'adult_pin': '/pin/service',
33         'metadata': '/metadata',
34         'set_video_rating': '/setVideoRating',
35         'update_my_list': '/playlistop'
36     }
37     """:obj:`dict` of :obj:`str` List of all static endpoints for HTML/JSON POST/GET requests"""
38
39     video_list_keys = ['user', 'genres', 'recommendations']
40     """:obj:`list` of :obj:`str` Divide the users video lists into 3 different categories (for easier digestion)"""
41
42     profiles = {}
43     """:obj:`dict`
44         Dict of user profiles, user id is the key:
45
46         "72ERT45...": {
47             "profileName": "username",
48             "avatar": "http://..../avatar.png",
49             "id": "72ERT45...",
50             "isAccountOwner": False,
51             "isActive": True,
52             "isFirstUse": False
53         }
54     """
55
56     user_data = {}
57     """:obj:`dict`
58         dict of user data (used for authentication):
59
60         {
61             "guid": "72ERT45...",
62             "authURL": "145637....",
63             "gpsModel": "harris"
64         }
65     """
66
67     api_data = {}
68     """:obj:`dict`
69         dict of api data (used to build up the api urls):
70
71         {
72             "API_BASE_URL": "/shakti",
73             "API_ROOT": "https://www.netflix.com/api",
74             "BUILD_IDENTIFIER": "113b89c9", "
75             ICHNAEA_ROOT": "/ichnaea"
76         }
77     """
78
79     esn = ''
80     """str: ESN - something like: NFCDCH-MC-D7D6F54LOPY8J416T72MQXX3RD20ME"""
81
82     def __init__(self, cookie_path, data_path, verify_ssl=True, log_fn=noop):
83         """Stores the cookie path for later use & instanciates a requests
84            session with a proper user agent & stored cookies/data if available
85
86         Parameters
87         ----------
88         cookie_path : :obj:`str`
89             Cookie location
90
91         data_path : :obj:`str`
92             User data cache location
93
94         log_fn : :obj:`fn`
95              optional log function
96         """
97         self.cookie_path = cookie_path
98         self.data_path = data_path
99         self.verify_ssl = verify_ssl
100         self.log = log_fn
101
102         # start session, fake chrome on the current platform (so that we get a proper widevine esn) & enable gzip
103         self.session = session()
104         self.session.headers.update({
105             'User-Agent': self._get_user_agent_for_current_platform(),
106             'Accept-Encoding': 'gzip'
107         })
108
109     def parse_login_form_fields (self, form_soup):
110         """Fetches all the inputfields from the login form, so that we
111            can build a request with all the fields needed besides the known email & password ones
112
113         Parameters
114         ----------
115         form_soup : :obj:`BeautifulSoup`
116             Instance of an BeautifulSoup documet or node containing the login form
117
118         Returns
119         -------
120             :obj:`dict` of :obj:`str`
121                 Dictionary of all input fields with their name as the key & the default
122                 value from the form field
123         """
124         login_input_fields = {}
125         login_inputs = form_soup.find_all('input')
126         # gather all form fields, set an empty string as the default value
127         for item in login_inputs:
128             keys = dict(item.attrs).keys()
129             if 'name' in keys and 'value' not in keys:
130                 login_input_fields[item['name']] = ''
131             elif 'name' in keys and 'value' in keys:
132                 login_input_fields[item['name']] = item['value']
133         return login_input_fields
134
135     def extract_inline_netflix_page_data (self, page_soup):
136         """Extracts all <script/> tags from the given document and parses the contents of each one of `em.
137         The contents of the parsable tags looks something like this:
138             <script>window.netflix = window.netflix || {} ; netflix.notification = {"constants":{"sessionLength":30,"ownerToken":"ZDD...};</script>
139         We use a JS parser to generate an AST of the code given & then parse that AST into a python dict.
140         This should be okay, as we´re only interested in a few static values & put the rest aside
141
142         Parameters
143         ----------
144         page_soup : :obj:`BeautifulSoup`
145             Instance of an BeautifulSoup document or node containing the complete page contents
146         Returns
147         -------
148             :obj:`list` of :obj:`dict`
149                 List of all the serialized data pulled out of the pagws <script/> tags
150         """
151         scripts = page_soup.find_all('script', attrs={'src': None});
152         self.log('Trying sloppy inline data parser')
153         inline_data = self._sloppy_parse_inline_data(scripts=scripts)
154         if self._verfify_auth_and_profiles_data(data=inline_data) != False:
155             self.log('Sloppy inline data parsing successfull')
156             return inline_data
157         self.log('Sloppy inline parser failed, trying JS parser')
158         return self._accurate_parse_inline_data(scripts=scripts)
159
160     def is_logged_in (self, account):
161         """Determines if a user is already logged in (with a valid cookie),
162            by fetching the index page with the current cookie & checking for the
163            `membership status` user data
164
165         Parameters
166         ----------
167         account : :obj:`dict` of :obj:`str`
168             Dict containing an email, country & a password property
169
170         Returns
171         -------
172         bool
173             User is already logged in (e.g. Cookie is valid) or not
174         """
175         is_logged_in = False
176         # load cookies
177         account_hash = self._generate_account_hash(account=account)
178         if self._load_cookies(filename=self.cookie_path + '_' + account_hash) == False:
179             return False
180         if self._load_data(filename=self.data_path + '_' + account_hash) == False:
181             # load the profiles page (to verify the user)
182             response = self._session_get(component='profiles')
183
184             # parse out the needed inline information
185             only_script_tags = SoupStrainer('script')
186             page_soup = BeautifulSoup(response.text, 'html.parser', parse_only=only_script_tags)
187             page_data = self._parse_page_contents(page_soup=page_soup)
188
189             # check if the cookie is still valid
190             for item in page_data:
191                 if 'profilesList' in dict(item).keys():
192                     if item['profilesList']['summary']['length'] >= 1:
193                         is_logged_in = True
194             return is_logged_in
195         return True
196
197     def logout (self):
198         """Delete all cookies and session data
199
200         Parameters
201         ----------
202         account : :obj:`dict` of :obj:`str`
203             Dict containing an email, country & a password property
204
205         """
206         self._delete_cookies(path=self.cookie_path)
207         self._delete_data(path=self.data_path)
208
209     def login (self, account):
210         """Try to log in a user with its credentials & stores the cookies if the action is successfull
211
212            Note: It fetches the HTML of the login page to extract the fields of the login form,
213            again, this is dirty, but as the fields & their values could change at any time, this
214            should be the most reliable way of retrieving the information
215
216         Parameters
217         ----------
218         account : :obj:`dict` of :obj:`str`
219             Dict containing an email, country & a password property
220
221         Returns
222         -------
223         bool
224             User could be logged in or not
225         """
226         response = self._session_get(component='login')
227         if response.status_code != 200:
228             return False;
229
230         # collect all the login fields & their contents and add the user credentials
231         page_soup = BeautifulSoup(response.text, 'html.parser')
232         login_form = page_soup.find(attrs={'class' : 'ui-label-text'}).findPrevious('form')
233         login_payload = self.parse_login_form_fields(form_soup=login_form)
234         if 'email' in login_payload:
235             login_payload['email'] = account['email']
236         if 'emailOrPhoneNumber' in login_payload:
237             login_payload['emailOrPhoneNumber'] = account['email']
238         login_payload['password'] = account['password']
239
240         # perform the login
241         login_response = self._session_post(component='login', data=login_payload)
242         login_soup = BeautifulSoup(login_response.text, 'html.parser')
243
244         # we know that the login was successfull if we find an HTML element with the class of 'profile-name'
245         if login_soup.find(attrs={'class' : 'profile-name'}) or login_soup.find(attrs={'class' : 'profile-icon'}):
246             # parse the needed inline information & store cookies for later requests
247             self._parse_page_contents(page_soup=login_soup)
248             account_hash = self._generate_account_hash(account=account)
249             self._save_cookies(filename=self.cookie_path + '_' + account_hash)
250             self._save_data(filename=self.data_path + '_' + account_hash)
251             return True
252         else:
253             return False
254
255     def switch_profile (self, profile_id, account):
256         """Switch the user profile based on a given profile id
257
258         Note: All available profiles & their ids can be found in the ´profiles´ property after a successfull login
259
260         Parameters
261         ----------
262         profile_id : :obj:`str`
263             User profile id
264
265         account : :obj:`dict` of :obj:`str`
266             Dict containing an email, country & a password property
267
268         Returns
269         -------
270         bool
271             User could be switched or not
272         """
273         payload = {
274             'switchProfileGuid': profile_id,
275             '_': int(time()),
276             'authURL': self.user_data['authURL']
277         }
278
279         response = self._session_get(component='switch_profiles', type='api', params=payload)
280         if response.status_code != 200:
281             return False
282
283         account_hash = self._generate_account_hash(account=account)
284         self.user_data['guid'] = profile_id;
285         return self._save_data(filename=self.data_path + '_' + account_hash)
286
287     def send_adult_pin (self, pin):
288         """Send the adult pin to Netflix in case an adult rated video requests it
289
290         Note: Once entered, it should last for the complete session (Not so sure about this)
291
292         Parameters
293         ----------
294         pin : :obj:`str`
295             The users adult pin
296
297         Returns
298         -------
299         bool
300             Pin was accepted or not
301         or
302         :obj:`dict` of :obj:`str`
303             Api call error
304         """
305         payload = {
306             'pin': pin,
307             'authURL': self.user_data['authURL']
308         }
309         response = self._session_get(component='adult_pin', params=payload)
310         pin_response = self._process_response(response=response, component=self._get_api_url_for(component='adult_pin'))
311         keys = pin_response.keys()
312         if 'success' in keys:
313             return True
314         if 'error' in keys:
315             return pin_response
316         return False
317
318     def add_to_list (self, video_id):
319         """Adds a video to "my list" on Netflix
320
321         Parameters
322         ----------
323         video_id : :obj:`str`
324             ID of th show/video/movie to be added
325
326         Returns
327         -------
328         bool
329             Adding was successfull
330         """
331         return self._update_my_list(video_id=video_id, operation='add')
332
333     def remove_from_list (self, video_id):
334         """Removes a video from "my list" on Netflix
335
336         Parameters
337         ----------
338         video_id : :obj:`str`
339             ID of th show/video/movie to be removed
340
341         Returns
342         -------
343         bool
344             Removing was successfull
345         """
346         return self._update_my_list(video_id=video_id, operation='remove')
347
348     def rate_video (self, video_id, rating):
349         """Rate a video on Netflix
350
351         Parameters
352         ----------
353         video_id : :obj:`str`
354             ID of th show/video/movie to be rated
355
356         rating : :obj:`int`
357             Rating, must be between 0 & 10
358
359         Returns
360         -------
361         bool
362             Rating successfull or not
363         """
364
365         # dirty rating validation
366         ratun = int(rating)
367         if rating > 10 or rating < 0:
368             return False
369
370         # In opposition to Kodi, Netflix uses a rating from 0 to in 0.5 steps
371         if rating != 0:
372             rating = rating / 2
373
374         headers = {
375             'Content-Type': 'application/json',
376             'Accept': 'application/json, text/javascript, */*',
377         }
378
379         params = {
380             'titleid': video_id,
381             'rating': rating
382         }
383
384         payload = json.dumps({
385             'authURL': self.user_data['authURL']
386         })
387
388         response = self._session_post(component='set_video_rating', type='api', params=params, headers=headers, data=payload)
389         return response.status_code == 200
390
391     def parse_video_list_ids (self, response_data):
392         """Parse the list of video ids e.g. rip out the parts we need
393
394         Parameters
395         ----------
396         response_data : :obj:`dict` of :obj:`str`
397             Parsed response JSON from the ´fetch_video_list_ids´ call
398
399         Returns
400         -------
401         :obj:`dict` of :obj:`dict`
402             Video list ids in the format:
403
404             {
405                 "genres": {
406                     "3589e2c6-ca3b-48b4-a72d-34f2c09ffbf4_11568367": {
407                         "displayName": "US-Serien",
408                         "id": "3589e2c6-ca3b-48b4-a72d-34f2c09ffbf4_11568367",
409                         "index": 3,
410                         "name": "genre",
411                         "size": 38
412                     },
413                     "3589e2c6-ca3b-48b4-a72d-34f2c09ffbf4_11568368": {
414                         "displayName": ...
415                     },
416                 },
417                 "user": {
418                     "3589e2c6-ca3b-48b4-a72d-34f2c09ffbf4_11568364": {
419                         "displayName": "Meine Liste",
420                         "id": "3589e2c6-ca3b-48b4-a72d-34f2c09ffbf4_11568364",
421                         "index": 0,
422                         "name": "queue",
423                         "size": 2
424                     },
425                     "3589e2c6-ca3b-48b4-a72d-34f2c09ffbf4_11568365": {
426                         "displayName": ...
427                     },
428                 },
429                 "recommendations": {
430                     "3589e2c6-ca3b-48b4-a72d-34f2c09ffbf4_11568382": {
431                         "displayName": "Passend zu Family Guy",
432                         "id": "3589e2c6-ca3b-48b4-a72d-34f2c09ffbf4_11568382",
433                         "index": 18,
434                         "name": "similars",
435                         "size": 33
436                     },
437                     "3589e2c6-ca3b-48b4-a72d-34f2c09ffbf4_11568397": {
438                         "displayName": ...
439                     }
440                 }
441             }
442         """
443         # prepare the return dictionary
444         video_list_ids = {}
445         for key in self.video_list_keys:
446             video_list_ids[key] = {}
447
448         # subcatogorize the lists by their context
449         video_lists = response_data['lists']
450         for video_list_id in video_lists.keys():
451             video_list = video_lists[video_list_id]
452             if video_list['context'] == 'genre':
453                 video_list_ids['genres'].update(self.parse_video_list_ids_entry(id=video_list_id, entry=video_list))
454             elif video_list['context'] == 'similars' or video_list['context'] == 'becauseYouAdded':
455                 video_list_ids['recommendations'].update(self.parse_video_list_ids_entry(id=video_list_id, entry=video_list))
456             else:
457                 video_list_ids['user'].update(self.parse_video_list_ids_entry(id=video_list_id, entry=video_list))
458
459         return video_list_ids
460
461     def parse_video_list_ids_entry (self, id, entry):
462         """Parse a video id entry e.g. rip out the parts we need
463
464         Parameters
465         ----------
466         response_data : :obj:`dict` of :obj:`str`
467             Dictionary entry from the ´fetch_video_list_ids´ call
468
469         Returns
470         -------
471         id : :obj:`str`
472             Unique id of the video list
473
474         entry : :obj:`dict` of :obj:`str`
475             Video list entry in the format:
476
477             "3589e2c6-ca3b-48b4-a72d-34f2c09ffbf4_11568382": {
478                 "displayName": "Passend zu Family Guy",
479                 "id": "3589e2c6-ca3b-48b4-a72d-34f2c09ffbf4_11568382",
480                 "index": 18,
481                 "name": "similars",
482                 "size": 33
483             }
484         """
485         return {
486             id: {
487                 'id': id,
488                 'index': entry['index'],
489                 'name': entry['context'],
490                 'displayName': entry['displayName'],
491                 'size': entry['length']
492             }
493         }
494
495     def parse_search_results (self, response_data):
496         """Parse the list of search results, rip out the parts we need
497            and extend it with detailed show informations
498
499         Parameters
500         ----------
501         response_data : :obj:`dict` of :obj:`str`
502             Parsed response JSON from the `fetch_search_results` call
503
504         Returns
505         -------
506         :obj:`dict` of :obj:`dict` of :obj:`str`
507             Search results in the format:
508
509             {
510                 "70136140": {
511                     "boxarts": "https://art-s.nflximg.net/0d7af/d5c72668c35d3da65ae031302bd4ae1bcc80d7af.jpg",
512                     "detail_text": "Die legend\u00e4re und mit 13 Emmys nominierte Serie von Gene Roddenberry inspirierte eine ganze Generation.",
513                     "id": "70136140",
514                     "season_id": "70109435",
515                     "synopsis": "Unter Befehl von Captain Kirk begibt sich die Besatzung des Raumschiffs Enterprise in die Tiefen des Weltraums, wo sie fremde Galaxien und neue Zivilisationen erforscht.",
516                     "title": "Star Trek",
517                     "type": "show"
518                 },
519                 "70158329": {
520                     "boxarts": ...
521                 }
522             }
523         """
524         search_results = {}
525         raw_search_results = response_data['value']['videos']
526         for entry_id in raw_search_results:
527             if self._is_size_key(key=entry_id) == False:
528                 # fetch information about each show & build up a proper search results dictionary
529                 show = self.parse_show_list_entry(id=entry_id, entry=raw_search_results[entry_id])
530                 show[entry_id].update(self.parse_show_information(id=entry_id, response_data=self.fetch_show_information(id=entry_id, type=show[entry_id]['type'])))
531                 search_results.update(show)
532         return search_results
533
534     def parse_show_list_entry (self, id, entry):
535         """Parse a show entry e.g. rip out the parts we need
536
537         Parameters
538         ----------
539         response_data : :obj:`dict` of :obj:`str`
540             Dictionary entry from the ´fetch_show_information´ call
541
542         id : :obj:`str`
543             Unique id of the video list
544
545         Returns
546         -------
547         entry : :obj:`dict` of :obj:`dict` of :obj:`str`
548             Show list entry in the format:
549
550             {
551                 "3589e2c6-ca3b-48b4-a72d-34f2c09ffbf4_11568382": {
552                     "id": "3589e2c6-ca3b-48b4-a72d-34f2c09ffbf4_11568382",
553                     "title": "Enterprise",
554                     "boxarts": "https://art-s.nflximg.net/.../smth.jpg",
555                     "type": "show"
556                 }
557             }
558         """
559         return {
560             id: {
561                 'id': id,
562                 'title': entry['title'],
563                 'boxarts': entry['boxarts']['_342x192']['jpg']['url'],
564                 'type': entry['summary']['type']
565             }
566         }
567
568     def parse_video_list (self, response_data):
569         """Parse a list of videos
570
571         Parameters
572         ----------
573         response_data : :obj:`dict` of :obj:`str`
574             Parsed response JSON from the `fetch_video_list` call
575
576         Returns
577         -------
578         :obj:`dict` of :obj:`dict`
579             Video list in the format:
580
581             {
582                 "372203": {
583                     "artwork": null,
584                     "boxarts": {
585                       "big": "https://art-s.nflximg.net/5e7d3/b3b48749843fd3a36db11c319ffa60f96b55e7d3.jpg",
586                       "small": "https://art-s.nflximg.net/57543/a039845c2eb9186dc26019576d895bf5a1957543.jpg"
587                     },
588                     "cast": [
589                       "Christine Elise",
590                       "Brad Dourif",
591                       "Grace Zabriskie",
592                       "Jenny Agutter",
593                       "John Lafia",
594                       "Gerrit Graham",
595                       "Peter Haskell",
596                       "Alex Vincent",
597                       "Beth Grant"
598                     ],
599                     "creators": [],
600                     "directors": [],
601                     "episode_count": null,
602                     "genres": [
603                       "Horrorfilme"
604                     ],
605                     "id": "372203",
606                     "in_my_list": true,
607                     "interesting_moment": "https://art-s.nflximg.net/09544/ed4b3073394b4469fb6ec22b9df81a4f5cb09544.jpg",
608                     "list_id": "9588df32-f957-40e4-9055-1f6f33b60103_46891306",
609                     "maturity": {
610                       "board": "FSK",
611                       "description": "Nur f\u00fcr Erwachsene geeignet.",
612                       "level": 1000,
613                       "value": "18"
614                     },
615                     "quality": "540",
616                     "rating": 3.1707757,
617                     "regular_synopsis": "Ein Spielzeughersteller erweckt aus Versehen die Seele der M\u00f6rderpuppe Chucky erneut zum Leben, die sich unmittelbar wieder ihren m\u00f6rderischen Aktivit\u00e4ten zuwendet.",
618                     "runtime": 5028,
619                     "seasons_count": null,
620                     "seasons_label": null,
621                     "synopsis": "Die allseits beliebte, von D\u00e4monen besessene M\u00f6rderpuppe ist wieder da und verbreitet erneut Horror und Schrecken.",
622                     "tags": [
623                       "Brutal",
624                       "Spannend"
625                     ],
626                     "title": "Chucky 2 \u2013 Die M\u00f6rderpuppe ist wieder da",
627                     "type": "movie",
628                     "watched": false,
629                     "year": 1990
630                 },
631                 "80011356": {
632                     "artwork": null,
633                     "boxarts": {
634                       "big": "https://art-s.nflximg.net/7c10d/5dcc3fc8f08487e92507627068cfe26ef727c10d.jpg",
635                       "small": "https://art-s.nflximg.net/5bc0e/f3be361b8c594929062f90a8d9c6eb57fb75bc0e.jpg"
636                     },
637                     "cast": [
638                       "Bjarne M\u00e4del"
639                     ],
640                     "creators": [],
641                     "directors": [
642                       "Arne Feldhusen"
643                     ],
644                     "episode_count": 24,
645                     "genres": [
646                       "Deutsche Serien",
647                       "Serien",
648                       "Comedyserien"
649                     ],
650                     "id": "80011356",
651                     "in_my_list": true,
652                     "interesting_moment": "https://art-s.nflximg.net/0188e/19cd705a71ee08c8d2609ae01cd8a97a86c0188e.jpg",
653                     "list_id": "9588df32-f957-40e4-9055-1f6f33b60103_46891306",
654                     "maturity": {
655                       "board": "FSF",
656                       "description": "Geeignet ab 12 Jahren.",
657                       "level": 80,
658                       "value": "12"
659                     },
660                     "quality": "720",
661                     "rating": 4.4394655,
662                     "regular_synopsis": "Comedy-Serie \u00fcber die Erlebnisse eines Tatortreinigers, der seine schmutzige Arbeit erst beginnen kann, wenn die Polizei die Tatortanalyse abgeschlossen hat.",
663                     "runtime": null,
664                     "seasons_count": 5,
665                     "seasons_label": "5 Staffeln",
666                     "synopsis": "In den meisten Krimiserien werden Mordf\u00e4lle auf faszinierende und spannende Weise gel\u00f6st. Diese Serie ist anders.",
667                     "tags": [
668                       "Zynisch"
669                     ],
670                     "title": "Der Tatortreiniger",
671                     "type": "show",
672                     "watched": false,
673                     "year": 2015
674                 },
675             }
676         """
677         video_list = {};
678         raw_video_list = response_data['value']
679         netflix_list_id = self.parse_netflix_list_id(video_list=raw_video_list);
680         for video_id in raw_video_list['videos']:
681             if self._is_size_key(key=video_id) == False:
682                 video_list.update(self.parse_video_list_entry(id=video_id, list_id=netflix_list_id, video=raw_video_list['videos'][video_id], persons=raw_video_list['person'], genres=raw_video_list['genres']))
683         return video_list
684
685     def parse_video_list_entry (self, id, list_id, video, persons, genres):
686         """Parse a video list entry e.g. rip out the parts we need
687
688         Parameters
689         ----------
690         id : :obj:`str`
691             Unique id of the video
692
693         list_id : :obj:`str`
694             Unique id of the containing list
695
696         video : :obj:`dict` of :obj:`str`
697             Video entry from the ´fetch_video_list´ call
698
699         persons : :obj:`dict` of :obj:`dict` of :obj:`str`
700             List of persons with reference ids
701
702         persons : :obj:`dict` of :obj:`dict` of :obj:`str`
703             List of genres with reference ids
704
705         Returns
706         -------
707         entry : :obj:`dict` of :obj:`dict` of :obj:`str`
708             Video list entry in the format:
709
710            {
711               "372203": {
712                 "artwork": null,
713                 "boxarts": {
714                   "big": "https://art-s.nflximg.net/5e7d3/b3b48749843fd3a36db11c319ffa60f96b55e7d3.jpg",
715                   "small": "https://art-s.nflximg.net/57543/a039845c2eb9186dc26019576d895bf5a1957543.jpg"
716                 },
717                 "cast": [
718                   "Christine Elise",
719                   "Brad Dourif",
720                   "Grace Zabriskie",
721                   "Jenny Agutter",
722                   "John Lafia",
723                   "Gerrit Graham",
724                   "Peter Haskell",
725                   "Alex Vincent",
726                   "Beth Grant"
727                 ],
728                 "creators": [],
729                 "directors": [],
730                 "episode_count": null,
731                 "genres": [
732                   "Horrorfilme"
733                 ],
734                 "id": "372203",
735                 "in_my_list": true,
736                 "interesting_moment": "https://art-s.nflximg.net/09544/ed4b3073394b4469fb6ec22b9df81a4f5cb09544.jpg",
737                 "list_id": "9588df32-f957-40e4-9055-1f6f33b60103_46891306",
738                 "maturity": {
739                   "board": "FSK",
740                   "description": "Nur f\u00fcr Erwachsene geeignet.",
741                   "level": 1000,
742                   "value": "18"
743                 },
744                 "quality": "540",
745                 "rating": 3.1707757,
746                 "regular_synopsis": "Ein Spielzeughersteller erweckt aus Versehen die Seele der M\u00f6rderpuppe Chucky erneut zum Leben, die sich unmittelbar wieder ihren m\u00f6rderischen Aktivit\u00e4ten zuwendet.",
747                 "runtime": 5028,
748                 "seasons_count": null,
749                 "seasons_label": null,
750                 "synopsis": "Die allseits beliebte, von D\u00e4monen besessene M\u00f6rderpuppe ist wieder da und verbreitet erneut Horror und Schrecken.",
751                 "tags": [
752                   "Brutal",
753                   "Spannend"
754                 ],
755                 "title": "Chucky 2 \u2013 Die M\u00f6rderpuppe ist wieder da",
756                 "type": "movie",
757                 "watched": false,
758                 "year": 1990
759               }
760             }
761         """
762         season_info = self.parse_season_information_for_video(video=video)
763         return {
764             id: {
765                 'id': id,
766                 'list_id': list_id,
767                 'title': video['title'],
768                 'synopsis': video['synopsis'],
769                 'regular_synopsis': video['regularSynopsis'],
770                 'type': video['summary']['type'],
771                 'rating': video['userRating']['average'],
772                 'episode_count': season_info['episode_count'],
773                 'seasons_label': season_info['seasons_label'],
774                 'seasons_count': season_info['seasons_count'],
775                 'in_my_list': video['queue']['inQueue'],
776                 'year': video['releaseYear'],
777                 'runtime': self.parse_runtime_for_video(video=video),
778                 'watched': video['watched'],
779                 'tags': self.parse_tags_for_video(video=video),
780                 'genres': self.parse_genres_for_video(video=video, genres=genres),
781                 'quality': self.parse_quality_for_video(video=video),
782                 'cast': self.parse_cast_for_video(video=video, persons=persons),
783                 'directors': self.parse_directors_for_video(video=video, persons=persons),
784                 'creators': self.parse_creators_for_video(video=video, persons=persons),
785                 'maturity': {
786                     'board': None if 'board' not in video['maturity']['rating'].keys() else video['maturity']['rating']['board'],
787                     'value': None if 'value' not in video['maturity']['rating'].keys() else video['maturity']['rating']['value'],
788                     'description': None if 'maturityDescription' not in video['maturity']['rating'].keys() else video['maturity']['rating']['maturityDescription'],
789                     'level': None if 'maturityLevel' not in video['maturity']['rating'].keys() else video['maturity']['rating']['maturityLevel']
790                 },
791                 'boxarts': {
792                     'small': video['boxarts']['_342x192']['jpg']['url'],
793                     'big': video['boxarts']['_1280x720']['jpg']['url']
794                 },
795                 'interesting_moment': None if 'interestingMoment' not in video.keys() else video['interestingMoment']['_665x375']['jpg']['url'],
796                 'artwork': video['artWorkByType']['BILLBOARD']['_1280x720']['jpg']['url'],
797             }
798         }
799
800     def parse_creators_for_video (self, video, persons):
801         """Matches ids with person names to generate a list of creators
802
803         Parameters
804         ----------
805         video : :obj:`dict` of :obj:`str`
806             Dictionary entry for one video entry
807
808         persons : :obj:`dict` of :obj:`str`
809             Raw resposne of all persons delivered by the API call
810
811         Returns
812         -------
813         :obj:`list` of :obj:`str`
814             List of creators
815         """
816         creators = []
817         for person_key in dict(persons).keys():
818             if self._is_size_key(key=person_key) == False and person_key != 'summary':
819                 for creator_key in dict(video['creators']).keys():
820                     if self._is_size_key(key=creator_key) == False and creator_key != 'summary':
821                         if video['creators'][creator_key][1] == person_key:
822                             creators.append(persons[person_key]['name'])
823         return creators
824
825     def parse_directors_for_video (self, video, persons):
826         """Matches ids with person names to generate a list of directors
827
828         Parameters
829         ----------
830         video : :obj:`dict` of :obj:`str`
831             Dictionary entry for one video entry
832
833         persons : :obj:`dict` of :obj:`str`
834             Raw resposne of all persons delivered by the API call
835
836         Returns
837         -------
838         :obj:`list` of :obj:`str`
839             List of directors
840         """
841         directors = []
842         for person_key in dict(persons).keys():
843             if self._is_size_key(key=person_key) == False and person_key != 'summary':
844                 for director_key in dict(video['directors']).keys():
845                     if self._is_size_key(key=director_key) == False and director_key != 'summary':
846                         if video['directors'][director_key][1] == person_key:
847                             directors.append(persons[person_key]['name'])
848         return directors
849
850     def parse_cast_for_video (self, video, persons):
851         """Matches ids with person names to generate a list of cast members
852
853         Parameters
854         ----------
855         video : :obj:`dict` of :obj:`str`
856             Dictionary entry for one video entry
857
858         persons : :obj:`dict` of :obj:`str`
859             Raw resposne of all persons delivered by the API call
860
861         Returns
862         -------
863         :obj:`list` of :obj:`str`
864             List of cast members
865         """
866         cast = []
867         for person_key in dict(persons).keys():
868             if self._is_size_key(key=person_key) == False and person_key != 'summary':
869                 for cast_key in dict(video['cast']).keys():
870                     if self._is_size_key(key=cast_key) == False and cast_key != 'summary':
871                         if video['cast'][cast_key][1] == person_key:
872                             cast.append(persons[person_key]['name'])
873         return cast
874
875     def parse_genres_for_video (self, video, genres):
876         """Matches ids with genre names to generate a list of genres for a video
877
878         Parameters
879         ----------
880         video : :obj:`dict` of :obj:`str`
881             Dictionary entry for one video entry
882
883         genres : :obj:`dict` of :obj:`str`
884             Raw resposne of all genres delivered by the API call
885
886         Returns
887         -------
888         :obj:`list` of :obj:`str`
889             List of genres
890         """
891         video_genres = []
892         for genre_key in dict(genres).keys():
893             if self._is_size_key(key=genre_key) == False and genre_key != 'summary':
894                 for show_genre_key in dict(video['genres']).keys():
895                     if self._is_size_key(key=show_genre_key) == False and show_genre_key != 'summary':
896                         if video['genres'][show_genre_key][1] == genre_key:
897                             video_genres.append(genres[genre_key]['name'])
898         return video_genres
899
900     def parse_tags_for_video (self, video):
901         """Parses a nested list of tags, removes the not needed meta information & returns a raw string list
902
903         Parameters
904         ----------
905         video : :obj:`dict` of :obj:`str`
906             Dictionary entry for one video entry
907
908         Returns
909         -------
910         :obj:`list` of :obj:`str`
911             List of tags
912         """
913         tags = []
914         for tag_key in dict(video['tags']).keys():
915             if self._is_size_key(key=tag_key) == False and tag_key != 'summary':
916                 tags.append(video['tags'][tag_key]['name'])
917         return tags
918
919     def parse_season_information_for_video (self, video):
920         """Checks if the fiven video is a show (series) and returns season & episode information
921
922         Parameters
923         ----------
924         video : :obj:`dict` of :obj:`str`
925             Dictionary entry for one video entry
926
927         Returns
928         -------
929         :obj:`dict` of :obj:`str`
930             Episode count / Season Count & Season label if given
931         """
932         season_info = {
933             'episode_count': None,
934             'seasons_label': None,
935             'seasons_count': None
936         }
937         if video['summary']['type'] == 'show':
938             season_info = {
939                 'episode_count': video['episodeCount'],
940                 'seasons_label': video['numSeasonsLabel'],
941                 'seasons_count': video['seasonCount']
942             }
943         return season_info
944
945     def parse_quality_for_video (self, video):
946         """Transforms Netflix quality information in video resolution info
947
948         Parameters
949         ----------
950         video : :obj:`dict` of :obj:`str`
951             Dictionary entry for one video entry
952
953         Returns
954         -------
955         :obj:`str`
956             Quality of the video
957         """
958         quality = '720'
959         if video['videoQuality']['hasHD']:
960             quality = '1080'
961         if video['videoQuality']['hasUltraHD']:
962             quality = '4000'
963         return quality
964
965     def parse_runtime_for_video (self, video):
966         """Checks if the video is a movie & returns the runtime if given
967
968         Parameters
969         ----------
970         video : :obj:`dict` of :obj:`str`
971             Dictionary entry for one video entry
972
973         Returns
974         -------
975         :obj:`str`
976             Runtime of the video (in seconds)
977         """
978         runtime = None
979         if video['summary']['type'] != 'show':
980             runtime = video['runtime']
981         return runtime
982
983     def parse_netflix_list_id (self, video_list):
984         """Parse a video list and extract the list id
985
986         Parameters
987         ----------
988         video_list : :obj:`dict` of :obj:`str`
989             Netflix video list
990
991         Returns
992         -------
993         entry : :obj:`str` or None
994             Netflix list id
995         """
996         netflix_list_id = None
997         if 'lists' in video_list.keys():
998             for video_id in video_list['lists']:
999                 if self._is_size_key(key=video_id) == False:
1000                     netflix_list_id = video_id;
1001         return netflix_list_id
1002
1003     def parse_show_information (self, id, response_data):
1004         """Parse extended show information (synopsis, seasons, etc.)
1005
1006         Parameters
1007         ----------
1008         id : :obj:`str`
1009             Video id
1010
1011         response_data : :obj:`dict` of :obj:`str`
1012             Parsed response JSON from the `fetch_show_information` call
1013
1014         Returns
1015         -------
1016         entry : :obj:`dict` of :obj:`str`
1017         Show information in the format:
1018             {
1019                 "season_id": "80113084",
1020                 "synopsis": "Aus verzweifelter Geldnot versucht sich der Familienvater und Drucker Jochen als Geldf\u00e4lscher und rutscht dabei immer mehr in die dunkle Welt des Verbrechens ab."
1021                 "detail_text": "I´m optional"
1022             }
1023         """
1024         show = {}
1025         raw_show = response_data['value']['videos'][id]
1026         show.update({'synopsis': raw_show['regularSynopsis']})
1027         if 'evidence' in raw_show:
1028             show.update({'detail_text': raw_show['evidence']['value']['text']})
1029         if 'seasonList' in raw_show:
1030             show.update({'season_id': raw_show['seasonList']['current'][1]})
1031         return show
1032
1033     def parse_seasons (self, id, response_data):
1034         """Parse a list of seasons for a given show
1035
1036         Parameters
1037         ----------
1038         id : :obj:`str`
1039             Season id
1040
1041         response_data : :obj:`dict` of :obj:`str`
1042             Parsed response JSON from the `fetch_seasons_for_show` call
1043
1044         Returns
1045         -------
1046         entry : :obj:`dict` of :obj:`dict` of :obj:`str`
1047         Season information in the format:
1048             {
1049                 "80113084": {
1050                     "id": 80113084,
1051                     "text": "Season 1",
1052                     "shortName": "St. 1",
1053                     "boxarts": {
1054                       "big": "https://art-s.nflximg.net/5e7d3/b3b48749843fd3a36db11c319ffa60f96b55e7d3.jpg",
1055                       "small": "https://art-s.nflximg.net/57543/a039845c2eb9186dc26019576d895bf5a1957543.jpg"
1056                     },
1057                     "interesting_moment": "https://art-s.nflximg.net/09544/ed4b3073394b4469fb6ec22b9df81a4f5cb09544.jpg"
1058                 },
1059                 "80113085": {
1060                     "id": 80113085,
1061                     "text": "Season 2",
1062                     "shortName": "St. 2",
1063                     "boxarts": {
1064                       "big": "https://art-s.nflximg.net/5e7d3/b3b48749843fd3a36db11c319ffa60f96b55e7d3.jpg",
1065                       "small": "https://art-s.nflximg.net/57543/a039845c2eb9186dc26019576d895bf5a1957543.jpg"
1066                     },
1067                     "interesting_moment": "https://art-s.nflximg.net/09544/ed4b3073394b4469fb6ec22b9df81a4f5cb09544.jpg"
1068                 }
1069             }
1070         """
1071         seasons = {}
1072         raw_seasons = response_data['value']
1073         for season in raw_seasons['seasons']:
1074             if self._is_size_key(key=season) == False:
1075                 seasons.update(self.parse_season_entry(season=raw_seasons['seasons'][season], videos=raw_seasons['videos']))
1076         return seasons
1077
1078     def parse_season_entry (self, season, videos):
1079         """Parse a season list entry e.g. rip out the parts we need
1080
1081         Parameters
1082         ----------
1083         season : :obj:`dict` of :obj:`str`
1084             Season entry from the `fetch_seasons_for_show` call
1085
1086         Returns
1087         -------
1088         entry : :obj:`dict` of :obj:`dict` of :obj:`str`
1089             Season list entry in the format:
1090
1091             {
1092                 "80113084": {
1093                     "id": 80113084,
1094                     "text": "Season 1",
1095                     "shortName": "St. 1",
1096                     "boxarts": {
1097                       "big": "https://art-s.nflximg.net/5e7d3/b3b48749843fd3a36db11c319ffa60f96b55e7d3.jpg",
1098                       "small": "https://art-s.nflximg.net/57543/a039845c2eb9186dc26019576d895bf5a1957543.jpg"
1099                     },
1100                     "interesting_moment": "https://art-s.nflximg.net/09544/ed4b3073394b4469fb6ec22b9df81a4f5cb09544.jpg"
1101                 }
1102             }
1103         """
1104         # get art video key
1105         video_key = ''
1106         for key in videos.keys():
1107             if self._is_size_key(key=key) == False:
1108                 video_key = key
1109         # get season index
1110         sorting = {}
1111         for idx in videos[video_key]['seasonList']:
1112             if self._is_size_key(key=idx) == False and idx != 'summary':
1113                 sorting[int(videos[video_key]['seasonList'][idx][1])] = int(idx)
1114         return {
1115             season['summary']['id']: {
1116                 'idx': sorting[season['summary']['id']],
1117                 'id': season['summary']['id'],
1118                 'text': season['summary']['name'],
1119                 'shortName': season['summary']['shortName'],
1120                 'boxarts': {
1121                     'small': videos[video_key]['boxarts']['_342x192']['jpg']['url'],
1122                     'big': videos[video_key]['boxarts']['_1280x720']['jpg']['url']
1123                 },
1124                 'interesting_moment': videos[video_key]['interestingMoment']['_665x375']['jpg']['url'],
1125             }
1126         }
1127
1128     def parse_episodes_by_season (self, response_data):
1129         """Parse episodes for a given season/episode list
1130
1131         Parameters
1132         ----------
1133         response_data : :obj:`dict` of :obj:`str`
1134             Parsed response JSON from the `fetch_seasons_for_show` call
1135
1136         Returns
1137         -------
1138         entry : :obj:`dict` of :obj:`dict` of :obj:`str`
1139         Season information in the format:
1140
1141         {
1142           "70251729": {
1143             "banner": "https://art-s.nflximg.net/63a36/c7fdfe6604ef2c22d085ac5dca5f69874e363a36.jpg",
1144             "duration": 1387,
1145             "episode": 1,
1146             "fanart": "https://art-s.nflximg.net/74e02/e7edcc5cc7dcda1e94d505df2f0a2f0d22774e02.jpg",
1147             "genres": [
1148               "Serien",
1149               "Comedyserien"
1150             ],
1151             "id": 70251729,
1152             "mediatype": "episode",
1153             "mpaa": "FSK 16",
1154             "my_list": false,
1155             "playcount": 0,
1156             "plot": "Als die Griffins und andere Einwohner von Quahog in die Villa von James Woods eingeladen werden, muss pl\u00f6tzlich ein Mord aufgekl\u00e4rt werden.",
1157             "poster": "https://art-s.nflximg.net/72fd6/57088715e8d436fdb6986834ab39124b0a972fd6.jpg",
1158             "rating": 3.9111512,
1159             "season": 9,
1160             "thumb": "https://art-s.nflximg.net/be686/07680670a68da8749eba607efb1ae37f9e3be686.jpg",
1161             "title": "Und dann gab es weniger (Teil 1)",
1162             "year": 2010,
1163             "bookmark": -1
1164           },
1165           "70251730": {
1166             "banner": "https://art-s.nflximg.net/63a36/c7fdfe6604ef2c22d085ac5dca5f69874e363a36.jpg",
1167             "duration": 1379,
1168             "episode": 2,
1169             "fanart": "https://art-s.nflximg.net/c472c/6c10f9578bf2c1d0a183c2ccb382931efcbc472c.jpg",
1170             "genres": [
1171               "Serien",
1172               "Comedyserien"
1173             ],
1174             "id": 70251730,
1175             "mediatype": "episode",
1176             "mpaa": "FSK 16",
1177             "my_list": false,
1178             "playcount": 1,
1179             "plot": "Wer ist der M\u00f6rder? Nach zahlreichen Morden wird immer wieder jemand anderes verd\u00e4chtigt.",
1180             "poster": "https://art-s.nflximg.net/72fd6/57088715e8d436fdb6986834ab39124b0a972fd6.jpg",
1181             "rating": 3.9111512,
1182             "season": 9,
1183             "thumb": "https://art-s.nflximg.net/15a08/857d59126641987bec302bb147a802a00d015a08.jpg",
1184             "title": "Und dann gab es weniger (Teil 2)",
1185             "year": 2010,
1186             "bookmark": 1234
1187           },
1188         }
1189         """
1190         episodes = {}
1191         raw_episodes = response_data['value']['videos']
1192         for episode_id in raw_episodes:
1193             if self._is_size_key(key=episode_id) == False:
1194                 if (raw_episodes[episode_id]['summary']['type'] == 'episode'):
1195                     episodes.update(self.parse_episode(episode=raw_episodes[episode_id], genres=response_data['value']['genres']))
1196         return episodes
1197
1198     def parse_episode (self, episode, genres=None):
1199         """Parse episode from an list of episodes by season
1200
1201         Parameters
1202         ----------
1203         episode : :obj:`dict` of :obj:`str`
1204             Episode entry from the `fetch_episodes_by_season` call
1205
1206         Returns
1207         -------
1208         entry : :obj:`dict` of :obj:`dict` of :obj:`str`
1209         Episode information in the format:
1210
1211         {
1212           "70251729": {
1213             "banner": "https://art-s.nflximg.net/63a36/c7fdfe6604ef2c22d085ac5dca5f69874e363a36.jpg",
1214             "duration": 1387,
1215             "episode": 1,
1216             "fanart": "https://art-s.nflximg.net/74e02/e7edcc5cc7dcda1e94d505df2f0a2f0d22774e02.jpg",
1217             "genres": [
1218               "Serien",
1219               "Comedyserien"
1220             ],
1221             "id": 70251729,
1222             "mediatype": "episode",
1223             "mpaa": "FSK 16",
1224             "my_list": false,
1225             "playcount": 0,
1226             "plot": "Als die Griffins und andere Einwohner von Quahog in die Villa von James Woods eingeladen werden, muss pl\u00f6tzlich ein Mord aufgekl\u00e4rt werden.",
1227             "poster": "https://art-s.nflximg.net/72fd6/57088715e8d436fdb6986834ab39124b0a972fd6.jpg",
1228             "rating": 3.9111512,
1229             "season": 9,
1230             "thumb": "https://art-s.nflximg.net/be686/07680670a68da8749eba607efb1ae37f9e3be686.jpg",
1231             "title": "Und dann gab es weniger (Teil 1)",
1232             "year": 2010,
1233             "bookmark": 1234
1234           },
1235         }
1236         """
1237         return {
1238             episode['summary']['id']: {
1239                 'id': episode['summary']['id'],
1240                 'episode': episode['summary']['episode'],
1241                 'season': episode['summary']['season'],
1242                 'plot': episode['info']['synopsis'],
1243                 'duration': episode['info']['runtime'],
1244                 'title': episode['info']['title'],
1245                 'year': episode['info']['releaseYear'],
1246                 'genres': self.parse_genres_for_video(video=episode, genres=genres),
1247                 'mpaa': str(episode['maturity']['rating']['board']) + ' ' + str(episode['maturity']['rating']['value']),
1248                 'maturity': episode['maturity'],
1249                 'playcount': (0, 1)[episode['watched']],
1250                 'rating': episode['userRating']['average'],
1251                 'thumb': episode['info']['interestingMoments']['url'],
1252                 'fanart': episode['interestingMoment']['_1280x720']['jpg']['url'],
1253                 'poster': episode['boxarts']['_1280x720']['jpg']['url'],
1254                 'banner': episode['boxarts']['_342x192']['jpg']['url'],
1255                 'mediatype': {'episode': 'episode', 'movie': 'movie'}[episode['summary']['type']],
1256                 'my_list': episode['queue']['inQueue'],
1257                 'bookmark': episode['bookmarkPosition']
1258             }
1259         }
1260
1261     def fetch_browse_list_contents (self):
1262         """Fetches the HTML data for the lists on the landing page (browse page) of Netflix
1263
1264         Returns
1265         -------
1266         :obj:`BeautifulSoup`
1267             Instance of an BeautifulSoup document containing the complete page contents
1268         """
1269         response = self._session_get(component='browse')
1270         return BeautifulSoup(response.text, 'html.parser')
1271
1272     def fetch_video_list_ids (self, list_from=0, list_to=50):
1273         """Fetches the JSON with detailed information based on the lists on the landing page (browse page) of Netflix
1274
1275         Parameters
1276         ----------
1277         list_from : :obj:`int`
1278             Start entry for pagination
1279
1280         list_to : :obj:`int`
1281             Last entry for pagination
1282
1283         Returns
1284         -------
1285         :obj:`dict` of :obj:`dict` of :obj:`str`
1286             Raw Netflix API call response or api call error
1287         """
1288         payload = {
1289             'fromRow': list_from,
1290             'toRow': list_to,
1291             'opaqueImageExtension': 'jpg',
1292             'transparentImageExtension': 'png',
1293             '_': int(time()),
1294             'authURL': self.user_data['authURL']
1295         }
1296         response = self._session_get(component='video_list_ids', params=payload, type='api')
1297         return self._process_response(response=response, component=self._get_api_url_for(component='video_list_ids'))
1298
1299     def fetch_search_results (self, search_str, list_from=0, list_to=10):
1300         """Fetches the JSON which contains the results for the given search query
1301
1302         Parameters
1303         ----------
1304         search_str : :obj:`str`
1305             String to query Netflix search for
1306
1307         list_from : :obj:`int`
1308             Start entry for pagination
1309
1310         list_to : :obj:`int`
1311             Last entry for pagination
1312
1313         Returns
1314         -------
1315         :obj:`dict` of :obj:`dict` of :obj:`str`
1316             Raw Netflix API call response or api call error
1317         """
1318         # properly encode the search string
1319         encoded_search_string = quote(search_str)
1320
1321         paths = [
1322             ['search', encoded_search_string, 'titles', {'from': list_from, 'to': list_to}, ['summary', 'title']],
1323             ['search', encoded_search_string, 'titles', {'from': list_from, 'to': list_to}, 'boxarts', '_342x192', 'jpg'],
1324             ['search', encoded_search_string, 'titles', ['id', 'length', 'name', 'trackIds', 'requestId']],
1325             ['search', encoded_search_string, 'suggestions', 0, 'relatedvideos', {'from': list_from, 'to': list_to}, ['summary', 'title']],
1326             ['search', encoded_search_string, 'suggestions', 0, 'relatedvideos', {'from': list_from, 'to': list_to}, 'boxarts', '_342x192', 'jpg'],
1327             ['search', encoded_search_string, 'suggestions', 0, 'relatedvideos', ['id', 'length', 'name', 'trackIds', 'requestId']]
1328         ]
1329         response = self._path_request(paths=paths)
1330         return self._process_response(response=response, component='Search results')
1331
1332     def fetch_video_list (self, list_id, list_from=0, list_to=20):
1333         """Fetches the JSON which contains the contents of a given video list
1334
1335         Parameters
1336         ----------
1337         list_id : :obj:`str`
1338             Unique list id to query Netflix for
1339
1340         list_from : :obj:`int`
1341             Start entry for pagination
1342
1343         list_to : :obj:`int`
1344             Last entry for pagination
1345
1346         Returns
1347         -------
1348         :obj:`dict` of :obj:`dict` of :obj:`str`
1349             Raw Netflix API call response or api call error
1350         """
1351         paths = [
1352             ['lists', list_id, {'from': list_from, 'to': list_to}, ['summary', 'title', 'synopsis', 'regularSynopsis', 'evidence', 'queue', 'episodeCount', 'info', 'maturity', 'runtime', 'seasonCount', 'releaseYear', 'userRating', 'numSeasonsLabel', 'bookmarkPosition', 'watched', 'videoQuality']],
1353             ['lists', list_id, {'from': list_from, 'to': list_to}, 'cast', {'from': 0, 'to': 15}, ['id', 'name']],
1354             ['lists', list_id, {'from': list_from, 'to': list_to}, 'cast', 'summary'],
1355             ['lists', list_id, {'from': list_from, 'to': list_to}, 'genres', {'from': 0, 'to': 5}, ['id', 'name']],
1356             ['lists', list_id, {'from': list_from, 'to': list_to}, 'genres', 'summary'],
1357             ['lists', list_id, {'from': list_from, 'to': list_to}, 'tags', {'from': 0, 'to': 9}, ['id', 'name']],
1358             ['lists', list_id, {'from': list_from, 'to': list_to}, 'tags', 'summary'],
1359             ['lists', list_id, {'from': list_from, 'to': list_to}, ['creators', 'directors'], {'from': 0, 'to': 49}, ['id', 'name']],
1360             ['lists', list_id, {'from': list_from, 'to': list_to}, ['creators', 'directors'], 'summary'],
1361             ['lists', list_id, {'from': list_from, 'to': list_to}, 'bb2OGLogo', '_400x90', 'png'],
1362             ['lists', list_id, {'from': list_from, 'to': list_to}, 'boxarts', '_342x192', 'jpg'],
1363             ['lists', list_id, {'from': list_from, 'to': list_to}, 'boxarts', '_1280x720', 'jpg'],
1364             ['lists', list_id, {'from': list_from, 'to': list_to}, 'storyarts', '_1632x873', 'jpg'],
1365             ['lists', list_id, {'from': list_from, 'to': list_to}, 'interestingMoment', '_665x375', 'jpg'],
1366             ['lists', list_id, {'from': list_from, 'to': list_to}, 'artWorkByType', 'BILLBOARD', '_1280x720', 'jpg']
1367         ];
1368
1369         response = self._path_request(paths=paths)
1370         return self._process_response(response=response, component='Video list')
1371
1372     def fetch_video_list_information (self, video_ids):
1373         """Fetches the JSON which contains the detail information of a list of given video ids
1374
1375         Parameters
1376         ----------
1377         video_ids : :obj:`list` of :obj:`str`
1378             List of video ids to fetch detail data for
1379
1380         Returns
1381         -------
1382         :obj:`dict` of :obj:`dict` of :obj:`str`
1383             Raw Netflix API call response or api call error
1384         """
1385         paths = []
1386         for video_id in video_ids:
1387             paths.append(['videos', video_id, ['summary', 'title', 'synopsis', 'regularSynopsis', 'evidence', 'queue', 'episodeCount', 'info', 'maturity', 'runtime', 'seasonCount', 'releaseYear', 'userRating', 'numSeasonsLabel', 'bookmarkPosition', 'watched', 'videoQuality']])
1388             paths.append(['videos', video_id, 'cast', {'from': 0, 'to': 15}, ['id', 'name']])
1389             paths.append(['videos', video_id, 'cast', 'summary'])
1390             paths.append(['videos', video_id, 'genres', {'from': 0, 'to': 5}, ['id', 'name']])
1391             paths.append(['videos', video_id, 'genres', 'summary'])
1392             paths.append(['videos', video_id, 'tags', {'from': 0, 'to': 9}, ['id', 'name']])
1393             paths.append(['videos', video_id, 'tags', 'summary'])
1394             paths.append(['videos', video_id, ['creators', 'directors'], {'from': 0, 'to': 49}, ['id', 'name']])
1395             paths.append(['videos', video_id, ['creators', 'directors'], 'summary'])
1396             paths.append(['videos', video_id, 'bb2OGLogo', '_400x90', 'png'])
1397             paths.append(['videos', video_id, 'boxarts', '_342x192', 'jpg'])
1398             paths.append(['videos', video_id, 'boxarts', '_1280x720', 'jpg'])
1399             paths.append(['videos', video_id, 'storyarts', '_1632x873', 'jpg'])
1400             paths.append(['videos', video_id, 'interestingMoment', '_665x375', 'jpg'])
1401             paths.append(['videos', video_id, 'artWorkByType', 'BILLBOARD', '_1280x720', 'jpg'])
1402
1403         response = self._path_request(paths=paths)
1404         return self._process_response(response=response, component='fetch_video_list_information')
1405
1406     def fetch_metadata (self, id):
1407         """Fetches the JSON which contains the metadata for a given show/movie or season id
1408
1409         Parameters
1410         ----------
1411         id : :obj:`str`
1412             Show id, movie id or season id
1413
1414         Returns
1415         -------
1416         :obj:`dict` of :obj:`dict` of :obj:`str`
1417             Raw Netflix API call response or api call error
1418         """
1419         payload = {
1420             'movieid': id,
1421             'imageformat': 'jpg',
1422             '_': int(time())
1423         }
1424         response = self._session_get(component='metadata', params=payload, type='api')
1425         return self._process_response(response=response, component=self._get_api_url_for(component='metadata'))
1426
1427     def fetch_show_information (self, id, type):
1428         """Fetches the JSON which contains the detailed contents of a show
1429
1430         Parameters
1431         ----------
1432         id : :obj:`str`
1433             Unique show id to query Netflix for
1434
1435         type : :obj:`str`
1436             Can be 'movie' or 'show'
1437
1438         Returns
1439         -------
1440         :obj:`dict` of :obj:`dict` of :obj:`str`
1441             Raw Netflix API call response or api call error
1442         """
1443         # check if we have a show or a movie, the request made depends on this
1444         if type == 'show':
1445             paths = [
1446                 ['videos', id, ['requestId', 'regularSynopsis', 'evidence']],
1447                 ['videos', id, 'seasonList', 'current', 'summary']
1448             ]
1449         else:
1450             paths = [['videos', id, ['requestId', 'regularSynopsis', 'evidence']]]
1451         response = self._path_request(paths=paths)
1452         return self._process_response(response=response, component='Show information')
1453
1454     def fetch_seasons_for_show (self, id, list_from=0, list_to=30):
1455         """Fetches the JSON which contains the seasons of a given show
1456
1457         Parameters
1458         ----------
1459         id : :obj:`str`
1460             Unique show id to query Netflix for
1461
1462         list_from : :obj:`int`
1463             Start entry for pagination
1464
1465         list_to : :obj:`int`
1466             Last entry for pagination
1467
1468         Returns
1469         -------
1470         :obj:`dict` of :obj:`dict` of :obj:`str`
1471             Raw Netflix API call response or api call error
1472         """
1473         paths = [
1474             ['videos', id, 'seasonList', {'from': list_from, 'to': list_to}, 'summary'],
1475             ['videos', id, 'seasonList', 'summary'],
1476             ['videos', id, 'boxarts',  '_342x192', 'jpg'],
1477             ['videos', id, 'boxarts', '_1280x720', 'jpg'],
1478             ['videos', id, 'storyarts',  '_1632x873', 'jpg'],
1479             ['videos', id, 'interestingMoment', '_665x375', 'jpg']
1480         ]
1481         response = self._path_request(paths=paths)
1482         return self._process_response(response=response, component='Seasons')
1483
1484     def fetch_episodes_by_season (self, season_id, list_from=-1, list_to=40):
1485         """Fetches the JSON which contains the episodes of a given season
1486
1487         TODO: Add more metadata
1488
1489         Parameters
1490         ----------
1491         season_id : :obj:`str`
1492             Unique season_id id to query Netflix for
1493
1494         list_from : :obj:`int`
1495             Start entry for pagination
1496
1497         list_to : :obj:`int`
1498             Last entry for pagination
1499
1500         Returns
1501         -------
1502         :obj:`dict` of :obj:`dict` of :obj:`str`
1503             Raw Netflix API call response or api call error
1504         """
1505         paths = [
1506             ['seasons', season_id, 'episodes', {'from': list_from, 'to': list_to}, ['summary', 'queue', 'info', 'maturity', 'userRating', 'bookmarkPosition', 'creditOffset', 'watched', 'videoQuality']],
1507             #['videos', season_id, 'cast', {'from': 0, 'to': 15}, ['id', 'name']],
1508             #['videos', season_id, 'cast', 'summary'],
1509             #['videos', season_id, 'genres', {'from': 0, 'to': 5}, ['id', 'name']],
1510             #['videos', season_id, 'genres', 'summary'],
1511             #['videos', season_id, 'tags', {'from': 0, 'to': 9}, ['id', 'name']],
1512             #['videos', season_id, 'tags', 'summary'],
1513             #['videos', season_id, ['creators', 'directors'], {'from': 0, 'to': 49}, ['id', 'name']],
1514             #['videos', season_id, ['creators', 'directors'], 'summary'],
1515             ['seasons', season_id, 'episodes', {'from': list_from, 'to': list_to}, 'genres', {'from': 0, 'to': 1}, ['id', 'name']],
1516             ['seasons', season_id, 'episodes', {'from': list_from, 'to': list_to}, 'genres', 'summary'],
1517             ['seasons', season_id, 'episodes', {'from': list_from, 'to': list_to}, 'interestingMoment', '_1280x720', 'jpg'],
1518             ['seasons', season_id, 'episodes', {'from': list_from, 'to': list_to}, 'interestingMoment', '_665x375', 'jpg'],
1519             ['seasons', season_id, 'episodes', {'from': list_from, 'to': list_to}, 'boxarts', '_342x192', 'jpg'],
1520             ['seasons', season_id, 'episodes', {'from': list_from, 'to': list_to}, 'boxarts', '_1280x720', 'jpg']
1521         ]
1522         response = self._path_request(paths=paths)
1523         return self._process_response(response=response, component='fetch_episodes_by_season')
1524
1525     def refresh_session_data (self, account):
1526         """Reload the session data (profiles, user_data, api_data)
1527
1528         Parameters
1529         ----------
1530         account : :obj:`dict` of :obj:`str`
1531             Dict containing an email, country & a password property
1532         """
1533         # load the profiles page (to verify the user)
1534         response = self._session_get(component='profiles')
1535         # parse out the needed inline information
1536         only_script_tags = SoupStrainer('script')
1537         page_soup = BeautifulSoup(response.text, 'html.parser', parse_only=only_script_tags)
1538         page_data = self._parse_page_contents(page_soup=page_soup)
1539         account_hash = self._generate_account_hash(account=account)
1540         self._save_data(filename=self.data_path + '_' + account_hash)
1541
1542     def _path_request (self, paths):
1543         """Executes a post request against the shakti endpoint with Falcor style payload
1544
1545         Parameters
1546         ----------
1547         paths : :obj:`list` of :obj:`list`
1548             Payload with path querys for the Netflix Shakti API in Falcor style
1549
1550         Returns
1551         -------
1552         :obj:`requests.response`
1553             Response from a POST call made with Requests
1554         """
1555         headers = {
1556             'Content-Type': 'application/json',
1557             'Accept': 'application/json, text/javascript, */*',
1558         }
1559
1560         data = json.dumps({
1561             'paths': paths,
1562             'authURL': self.user_data['authURL']
1563         })
1564
1565         params = {
1566             'withSize': True,
1567             'materialize': True,
1568             'model': self.user_data['gpsModel']
1569         }
1570
1571         return self._session_post(component='shakti', type='api', params=params, headers=headers, data=data)
1572
1573     def _is_size_key (self, key):
1574         """Tiny helper that checks if a given key is called $size or size, as we need to check this often
1575
1576         Parameters
1577         ----------
1578         key : :obj:`str`
1579             Key to check the value for
1580
1581         Returns
1582         -------
1583         bool
1584             Key has a size value or not
1585         """
1586         return key == '$size' or key == 'size'
1587
1588     def _get_api_url_for (self, component):
1589         """Tiny helper that builds the url for a requested API endpoint component
1590
1591         Parameters
1592         ----------
1593         component : :obj:`str`
1594             Component endpoint to build the URL for
1595
1596         Returns
1597         -------
1598         :obj:`str`
1599             API Url
1600         """
1601         if self.api_data['API_ROOT'].find(self.api_data['API_BASE_URL']) > -1:
1602             return self.api_data['API_ROOT'] + '/' + self.api_data['BUILD_IDENTIFIER'] + self.urls[component]
1603         else:
1604             return self.api_data['API_ROOT'] + self.api_data['API_BASE_URL'] + '/' + self.api_data['BUILD_IDENTIFIER'] + self.urls[component]
1605
1606     def _get_document_url_for (self, component):
1607         """Tiny helper that builds the url for a requested document endpoint component
1608
1609         Parameters
1610         ----------
1611         component : :obj:`str`
1612             Component endpoint to build the URL for
1613
1614         Returns
1615         -------
1616         :obj:`str`
1617             Document Url
1618         """
1619         return self.base_url + self.urls[component]
1620
1621     def _process_response (self, response, component):
1622         """Tiny helper to check responses for API requests
1623
1624         Parameters
1625         ----------
1626         response : :obj:`requests.response`
1627             Response from a requests instance
1628
1629         component : :obj:`str`
1630             Component endpoint
1631
1632         Returns
1633         -------
1634         :obj:`dict` of :obj:`dict` of :obj:`str` or :obj:`dict` of :obj:`str`
1635             Raw Netflix API call response or api call error
1636         """
1637         # check if we´re not authorized to make thios call
1638         if response.status_code == 401:
1639             return {
1640                 'error': True,
1641                 'message': 'Session invalid',
1642                 'code': 401
1643             }
1644         # check if somethign else failed
1645         if response.status_code != 200:
1646             return {
1647                 'error': True,
1648                 'message': 'API call for "' + component + '" failed',
1649                 'code': response.status_code
1650             }
1651         # return the parsed response & everything´s fine
1652         return response.json()
1653
1654     def _to_unicode(self, str):
1655         '''Attempt to fix non uft-8 string into utf-8, using a limited set of encodings
1656
1657         Parameters
1658         ----------
1659         str : `str`
1660             String to decode
1661
1662         Returns
1663         -------
1664         `str`
1665             Decoded string
1666         '''
1667         # fuller list of encodings at http://docs.python.org/library/codecs.html#standard-encodings
1668         if not str:  return u''
1669         u = None
1670         # we could add more encodings here, as warranted.
1671         encodings = ('ascii', 'utf8', 'latin1')
1672         for enc in encodings:
1673             if u:  break
1674             try:
1675                 u = unicode(str,enc)
1676             except UnicodeDecodeError:
1677                 pass
1678         if not u:
1679             u = unicode(str, errors='replace')
1680         return u
1681
1682     def _update_my_list (self, video_id, operation):
1683         """Tiny helper to add & remove items from "my list"
1684
1685         Parameters
1686         ----------
1687         video_id : :obj:`str`
1688             ID of the show/movie to be added
1689
1690         operation : :obj:`str`
1691             Either "add" or "remove"
1692
1693         Returns
1694         -------
1695         bool
1696             Operation successfull
1697         """
1698         headers = {
1699             'Content-Type': 'application/json',
1700             'Accept': 'application/json, text/javascript, */*',
1701         }
1702
1703         payload = json.dumps({
1704             'operation': operation,
1705             'videoId': int(video_id),
1706             'authURL': self.user_data['authURL']
1707         })
1708
1709         response = self._session_post(component='update_my_list', type='api', headers=headers, data=payload)
1710         return response.status_code == 200
1711
1712     def _save_data(self, filename):
1713         """Tiny helper that stores session data from the session in a given file
1714
1715         Parameters
1716         ----------
1717         filename : :obj:`str`
1718             Complete path incl. filename that determines where to store the cookie
1719
1720         Returns
1721         -------
1722         bool
1723             Storage procedure was successfull
1724         """
1725         if not os.path.isdir(os.path.dirname(filename)):
1726             return False
1727         with open(filename, 'w') as f:
1728             f.truncate()
1729             pickle.dump({
1730                 'user_data': self.user_data,
1731                 'api_data': self.api_data,
1732                 'profiles': self.profiles
1733             }, f)
1734
1735     def _load_data(self, filename):
1736         """Tiny helper that loads session data into the active session from a given file
1737
1738         Parameters
1739         ----------
1740         filename : :obj:`str`
1741             Complete path incl. filename that determines where to load the data from
1742
1743         Returns
1744         -------
1745         bool
1746             Load procedure was successfull
1747         """
1748         if not os.path.isfile(filename):
1749             return False
1750
1751         with open(filename) as f:
1752             data = pickle.load(f)
1753             if data:
1754                 self.profiles = data['profiles']
1755                 self.user_data = data['user_data']
1756                 self.api_data = data['api_data']
1757             else:
1758                 return False
1759
1760     def _delete_data (self, path):
1761         """Tiny helper that deletes session data
1762
1763         Parameters
1764         ----------
1765         filename : :obj:`str`
1766             Complete path incl. filename that determines where to delete the files
1767
1768         """
1769         head, tail = os.path.split(path)
1770         for subdir, dirs, files in os.walk(head):
1771             for file in files:
1772                 if tail in file:
1773                     os.remove(os.path.join(subdir, file))
1774
1775     def _save_cookies(self, filename):
1776         """Tiny helper that stores cookies from the session in a given file
1777
1778         Parameters
1779         ----------
1780         filename : :obj:`str`
1781             Complete path incl. filename that determines where to store the cookie
1782
1783         Returns
1784         -------
1785         bool
1786             Storage procedure was successfull
1787         """
1788         if not os.path.isdir(os.path.dirname(filename)):
1789             return False
1790         with open(filename, 'w') as f:
1791             f.truncate()
1792             pickle.dump(self.session.cookies._cookies, f)
1793
1794     def _load_cookies(self, filename):
1795         """Tiny helper that loads cookies into the active session from a given file
1796
1797         Parameters
1798         ----------
1799         filename : :obj:`str`
1800             Complete path incl. filename that determines where to load the cookie from
1801
1802         Returns
1803         -------
1804         bool
1805             Load procedure was successfull
1806         """
1807         if not os.path.isfile(filename):
1808             return False
1809
1810         with open(filename) as f:
1811             _cookies = pickle.load(f)
1812             if _cookies:
1813                 jar = cookies.RequestsCookieJar()
1814                 jar._cookies = _cookies
1815                 self.session.cookies = jar
1816             else:
1817                 return False
1818
1819     def _delete_cookies (self, path):
1820         """Tiny helper that deletes cookie data
1821
1822         Parameters
1823         ----------
1824         filename : :obj:`str`
1825             Complete path incl. filename that determines where to delete the files
1826
1827         """
1828         head, tail = os.path.split(path)
1829         for subdir, dirs, files in os.walk(head):
1830             for file in files:
1831                 if tail in file:
1832                     os.remove(os.path.join(subdir, file))
1833
1834     def _generate_account_hash (self, account):
1835         """Generates a has for the given account (used for cookie verification)
1836
1837         Parameters
1838         ----------
1839         account : :obj:`dict` of :obj:`str`
1840             Dict containing an email, country & a password property
1841
1842         Returns
1843         -------
1844         :obj:`str`
1845             Account data hash
1846         """
1847         return urlsafe_b64encode(account['email'])
1848
1849     def _get_user_agent_for_current_platform (self):
1850         """Determines the user agent string for the current platform (to retrieve a valid ESN)
1851
1852         Returns
1853         -------
1854         :obj:`str`
1855             User Agent for platform
1856         """
1857         import platform
1858         if platform == 'linux' or platform == 'linux2':
1859             return 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36'
1860         elif platform == 'darwin':
1861             return 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36'
1862         elif platform == 'win32':
1863             return 'Mozilla/5.0 (Windows NT 6.1; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36'
1864         else:
1865             return 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/56.0.2924.87 Safari/537.36'
1866
1867     def _session_post (self, component, type='document', data={}, headers={}, params={}):
1868         """Executes a get request using requests for the current session & measures the duration of that request
1869
1870         Parameters
1871         ----------
1872         component : :obj:`str`
1873             Component to query
1874
1875         type : :obj:`str`
1876             Is it a document or API request ('document' is default)
1877
1878         data : :obj:`dict` of :obj:`str`
1879             Payload body as dict
1880
1881         header : :obj:`dict` of :obj:`str`
1882             Additional headers as dict
1883
1884         params : :obj:`dict` of :obj:`str`
1885             Request params
1886
1887         Returns
1888         -------
1889             :obj:`str`
1890                 Contents of the field to match
1891         """
1892         url = self._get_document_url_for(component=component) if type == 'document' else self._get_api_url_for(component=component)
1893         start = time()
1894         response = self.session.post(url=url, data=data, params=params, headers=headers, verify=self.verify_ssl)
1895         end = time()
1896         self.log('[POST] Request for "' + url + '" took ' + str(end - start) + ' seconds')
1897         return response
1898
1899     def _session_get (self, component, type='document', params={}):
1900         """Executes a get request using requests for the current session & measures the duration of that request
1901
1902         Parameters
1903         ----------
1904         component : :obj:`str`
1905             Component to query
1906
1907         type : :obj:`str`
1908             Is it a document or API request ('document' is default)
1909
1910         params : :obj:`dict` of :obj:`str`
1911             Request params
1912
1913         Returns
1914         -------
1915             :obj:`str`
1916                 Contents of the field to match
1917         """
1918         url = self._get_document_url_for(component=component) if type == 'document' else self._get_api_url_for(component=component)
1919         start = time()
1920         response = self.session.get(url=url, verify=self.verify_ssl, params=params)
1921         end = time()
1922         self.log('[GET] Request for "' + url + '" took ' + str(end - start) + ' seconds')
1923         return response
1924
1925     def _sloppy_parse_user_and_api_data (self, key, contents):
1926         """Try to find the user & API data from the inline js by using a string parser
1927
1928         Parameters
1929         ----------
1930         key : :obj:`str`
1931             Key to match in the inline js
1932
1933         contents : :obj:`str`
1934             Inline JS contents
1935
1936         Returns
1937         -------
1938             :obj:`str`
1939                 Contents of the field to match
1940         """
1941         key_start = contents.find(key + '"')
1942         if int(key_start) == -1:
1943             return None
1944         sub_contents = contents[int(key_start):]
1945         l = sub_contents.find('",')
1946         return contents[(int(key_start)+len(key)+3):int(key_start)+l].decode('string_escape')
1947
1948     def _sloppy_parse_profiles (self, contents):
1949         """Try to find the profile data from the inline js by using a string parser & parse/convert the result to JSON
1950
1951         Parameters
1952         ----------
1953         contents : :obj:`str`
1954             Inline JS contents
1955
1956         Returns
1957         -------
1958             :obj:`dict` of :obj:`str` or None
1959                 Profile data
1960         """
1961         profile_start = contents.find('profiles":')
1962         profile_list_start = contents.find('profilesList')
1963         if int(profile_start) > -1 and int(profile_list_start) > -1:
1964             try:
1965                 try:
1966                     return json.loads('{"a":{"' + contents[profile_start:profile_list_start-2].decode('string_escape') + '}}').get('a').get('profiles')
1967                 except ValueError, e:
1968                    return None
1969             except TypeError, e:
1970                 return None
1971         return None
1972
1973     def _sloppy_parse_avatars (self, contents):
1974         """Try to find the avatar data from the inline js by using a string parser & parse/convert the result to JSON
1975
1976         Parameters
1977         ----------
1978         contents : :obj:`str`
1979             Inline JS contents
1980
1981         Returns
1982         -------
1983             :obj:`dict` of :obj:`str` or None
1984                 Avatar data
1985         """
1986         avatars_start = contents.find('"nf":')
1987         avatars_list_start = contents.find('"profiles"')
1988         if int(avatars_start) > -1 and int(avatars_list_start) > -1:
1989             try:
1990                 try:
1991                     return json.loads('{' + contents[avatars_start:avatars_list_start-2].decode('string_escape') + '}')
1992                 except ValueError, e:
1993                    return None
1994             except TypeError, e:
1995                 return None
1996         return None
1997
1998     def _verfify_auth_and_profiles_data (self, data):
1999         """Checks if the authURL has at least a certain length & doesn't overrule a certain length & if the profiles dict exists
2000         Simple validity check for the sloppy data parser
2001
2002         Parameters
2003         ----------
2004         data : :obj:`dict` of :obj:`str`
2005             Parsed JS contents
2006
2007         Returns
2008         -------
2009             bool
2010                 Data is valid
2011         """
2012         if type(data.get('profiles')) == dict:
2013             if len(str(data.get('authURL', ''))) > 10 and len(str(data.get('authURL', ''))) < 50:
2014                 return True
2015         return False
2016
2017     def _sloppy_parse_inline_data (self, scripts):
2018         """Strips out all the needed user, api & profile data from the inline JS by string parsing
2019         Might fail, so if this doesn't succeed, a proper JS parser will chime in
2020
2021         Note: This has been added for performance reasons only
2022
2023         Parameters
2024         ----------
2025         scripts : :obj:`list` of :obj:`BeautifoulSoup`
2026             Script tags & contents from the Netflix browse page
2027
2028         Returns
2029         -------
2030             :obj:`dict` of :obj:`str`
2031                 Dict containijg user, api & profile data
2032         """
2033         inline_data = {};
2034         for script in scripts:
2035             contents = str(script.contents[0])
2036             important_data = ['authURL', 'API_BASE_URL', 'API_ROOT', 'BUILD_IDENTIFIER', 'ICHNAEA_ROOT', 'gpsModel', 'guid', 'esn']
2037             res = {}
2038             for key in important_data:
2039                 _res = self._sloppy_parse_user_and_api_data(key, contents)
2040                 if _res != None:
2041                     res.update({key: _res})
2042             if res != {}:
2043                 inline_data.update(res)
2044
2045             # parse profiles
2046             profiles = self._sloppy_parse_profiles(contents)
2047             avatars = self._sloppy_parse_avatars(contents)
2048             if profiles != None:
2049                 inline_data.update({'profiles': profiles})
2050             if avatars != None:
2051                 inline_data.update(avatars)
2052         return inline_data
2053
2054     def _accurate_parse_inline_data (self, scripts):
2055         """Uses a proper JS parser to fetch all the api, iser & profile data from within the inline JS
2056
2057         Note: This is slow but accurate
2058
2059         Parameters
2060         ----------
2061         scripts : :obj:`list` of :obj:`BeautifoulSoup`
2062             Script tags & contents from the Netflix browse page
2063
2064         Returns
2065         -------
2066             :obj:`dict` of :obj:`str`
2067                 Dict containing user, api & profile data
2068         """
2069         inline_data = []
2070         from pyjsparser import PyJsParser
2071         parser = PyJsParser()
2072         for script in scripts:
2073             data = {}
2074             # unicode escape that incoming script stuff
2075             contents = self._to_unicode(str(script.contents[0]))
2076             # parse the JS & load the declarations we´re interested in
2077             parsed = parser.parse(contents)
2078             if len(parsed['body']) > 1 and parsed['body'][1]['expression']['right'].get('properties', None) != None:
2079                 declarations = parsed['body'][1]['expression']['right']['properties']
2080                 for declaration in declarations:
2081                     for key in declaration:
2082                         # we found the correct path if the declaration is a dict & of type 'ObjectExpression'
2083                         if type(declaration[key]) is dict:
2084                             if declaration[key]['type'] == 'ObjectExpression':
2085                                 # add all static data recursivly
2086                                 for expression in declaration[key]['properties']:
2087                                     data[expression['key']['value']] = self._parse_rec(expression['value'])
2088                     inline_data.append(data)
2089         return inline_data
2090
2091     def _parse_rec (self, node):
2092         """Iterates over a JavaScript AST and return values found
2093
2094         Parameters
2095         ----------
2096         value : :obj:`dict`
2097             JS AST Expression
2098         Returns
2099         -------
2100         :obj:`dict` of :obj:`dict` or :obj:`str`
2101             Parsed contents of the node
2102         """
2103         if node['type'] == 'ObjectExpression':
2104             _ret = {}
2105             for prop in node['properties']:
2106                 _ret.update({prop['key']['value']: self._parse_rec(prop['value'])})
2107             return _ret
2108         if node['type'] == 'Literal':
2109             return node['value']
2110
2111     def _parse_user_data (self, netflix_page_data):
2112         """Parse out the user data from the big chunk of dicts we got from
2113            parsing the JSON-ish data from the netflix homepage
2114
2115         Parameters
2116         ----------
2117         netflix_page_data : :obj:`list`
2118             List of all the JSON-ish data that has been extracted from the Netflix homepage
2119             see: extract_inline_netflix_page_data
2120
2121         Returns
2122         -------
2123             :obj:`dict` of :obj:`str`
2124
2125             {
2126                 "guid": "72ERT45...",
2127                 "authURL": "145637....",
2128                 "gpsModel": "harris"
2129             }
2130         """
2131         user_data = {};
2132         important_fields = [
2133             'authURL',
2134             'gpsModel',
2135             'guid'
2136         ]
2137
2138         # values are accessible via dict (sloppy parsing successfull)
2139         if type(netflix_page_data) == dict:
2140             for important_field in important_fields:
2141                 user_data.update({important_field: netflix_page_data.get(important_field, '')})
2142             return user_data
2143
2144         # values are stored in lists (returned from JS parser)
2145         for item in netflix_page_data:
2146             if 'memberContext' in dict(item).keys():
2147                 for important_field in important_fields:
2148                     user_data.update({important_field: item['memberContext']['data']['userInfo'][important_field]})
2149
2150         return user_data
2151
2152     def _parse_profile_data (self, netflix_page_data):
2153         """Parse out the profile data from the big chunk of dicts we got from
2154            parsing the JSON-ish data from the netflix homepage
2155
2156         Parameters
2157         ----------
2158         netflix_page_data : :obj:`list`
2159             List of all the JSON-ish data that has been extracted from the Netflix homepage
2160             see: extract_inline_netflix_page_data
2161
2162         Returns
2163         -------
2164             :obj:`dict` of :obj:`dict
2165
2166             {
2167                 "72ERT45...": {
2168                     "profileName": "username",
2169                     "avatar": "http://..../avatar.png",
2170                     "id": "72ERT45...",
2171                     "isAccountOwner": False,
2172                     "isActive": True,
2173                     "isFirstUse": False
2174                 }
2175             }
2176         """
2177         profiles = {};
2178         important_fields = [
2179             'profileName',
2180             'isActive',
2181             'isFirstUse',
2182             'isAccountOwner'
2183         ]
2184
2185         # values are accessible via dict (sloppy parsing successfull)
2186         if type(netflix_page_data) == dict:
2187             for profile_id in netflix_page_data.get('profiles'):
2188                 if self._is_size_key(key=profile_id) == False and type(netflix_page_data['profiles'][profile_id]) == dict and netflix_page_data['profiles'][profile_id].get('avatar', False) != False:
2189                     profile = {'id': profile_id}
2190                     for important_field in important_fields:
2191                         profile.update({important_field: netflix_page_data['profiles'][profile_id]['summary'][important_field]})
2192                     avatar_base = netflix_page_data['nf'].get(netflix_page_data['profiles'][profile_id]['summary']['avatarName'], False);
2193                     avatar = 'https://secure.netflix.com/ffe/profiles/avatars_v2/320x320/PICON_029.png' if avatar_base == False else avatar_base['images']['byWidth']['320']['value']
2194                     profile.update({'avatar': avatar})
2195                     profiles.update({profile_id: profile})
2196             return profiles
2197
2198         # values are stored in lists (returned from JS parser)
2199         # TODO: get rid of this christmas tree of doom
2200         for item in netflix_page_data:
2201             if 'hasViewedRatingWelcomeModal' in dict(item).keys():
2202                 for profile_id in item:
2203                     if self._is_size_key(key=profile_id) == False and type(item[profile_id]) == dict and item[profile_id].get('avatar', False) != False:
2204                         profile = {'id': profile_id}
2205                         for important_field in important_fields:
2206                             profile.update({important_field: item[profile_id]['summary'][important_field]})
2207                         avatar_base = item['nf'].get(item[profile_id]['summary']['avatarName'], False);
2208                         avatar = 'https://secure.netflix.com/ffe/profiles/avatars_v2/320x320/PICON_029.png' if avatar_base == False else avatar_base['images']['byWidth']['320']['value']
2209                         profile.update({'avatar': avatar})
2210                         profiles.update({profile_id: profile})
2211         return profiles
2212
2213     def _parse_api_base_data (self, netflix_page_data):
2214         """Parse out the api url data from the big chunk of dicts we got from
2215            parsing the JSOn-ish data from the netflix homepage
2216
2217         Parameters
2218         ----------
2219         netflix_page_data : :obj:`list`
2220             List of all the JSON-ish data that has been extracted from the Netflix homepage
2221             see: extract_inline_netflix_page_data
2222
2223         Returns
2224         -------
2225             :obj:`dict` of :obj:`str
2226
2227             {
2228                 "API_BASE_URL": "/shakti",
2229                 "API_ROOT": "https://www.netflix.com/api",
2230                 "BUILD_IDENTIFIER": "113b89c9",
2231                 "ICHNAEA_ROOT": "/ichnaea"
2232             }
2233         """
2234         api_data = {};
2235         important_fields = [
2236             'API_BASE_URL',
2237             'API_ROOT',
2238             'BUILD_IDENTIFIER',
2239             'ICHNAEA_ROOT'
2240         ]
2241
2242         # values are accessible via dict (sloppy parsing successfull)
2243         if type(netflix_page_data) == dict:
2244             for important_field in important_fields:
2245                 api_data.update({important_field: netflix_page_data.get(important_field, '')})
2246             return api_data
2247
2248         for item in netflix_page_data:
2249             if 'serverDefs' in dict(item).keys():
2250                 for important_field in important_fields:
2251                     api_data.update({important_field: item['serverDefs']['data'][important_field]})
2252         return api_data
2253
2254     def _parse_esn_data (self, netflix_page_data):
2255         """Parse out the esn id data from the big chunk of dicts we got from
2256            parsing the JSOn-ish data from the netflix homepage
2257
2258         Parameters
2259         ----------
2260         netflix_page_data : :obj:`list`
2261             List of all the JSON-ish data that has been extracted from the Netflix homepage
2262             see: extract_inline_netflix_page_data
2263
2264         Returns
2265         -------
2266             :obj:`str` of :obj:`str
2267             ESN, something like: NFCDCH-MC-D7D6F54LOPY8J416T72MQXX3RD20ME
2268         """
2269         esn = ''
2270         # values are accessible via dict (sloppy parsing successfull)
2271         if type(netflix_page_data) == dict:
2272             return netflix_page_data.get('esn', '')
2273
2274         # values are stored in lists (returned from JS parser)
2275         for item in netflix_page_data:
2276             if 'esnGeneratorModel' in dict(item).keys():
2277                 esn = item['esnGeneratorModel']['data']['esn']
2278         return esn
2279
2280     def _parse_page_contents (self, page_soup):
2281         """Call all the parsers we need to extract all the session relevant data from the HTML page
2282            Directly assigns it to the NetflixSession instance
2283
2284         Parameters
2285         ----------
2286         page_soup : :obj:`BeautifulSoup`
2287             Instance of an BeautifulSoup document or node containing the complete page contents
2288         """
2289         netflix_page_data = self.extract_inline_netflix_page_data(page_soup=page_soup)
2290         self.user_data = self._parse_user_data(netflix_page_data=netflix_page_data)
2291         self.esn = self._parse_esn_data(netflix_page_data=netflix_page_data)
2292         self.api_data = self._parse_api_base_data(netflix_page_data=netflix_page_data)
2293         self.profiles = self._parse_profile_data(netflix_page_data=netflix_page_data)
2294         self.log('Found ESN "' + self.esn + '"')
2295         return netflix_page_data