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