imdbpie 5.8.0__py3-none-any.whl

imdbpie/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+from .imdbpie import Imdb  # noqa
+from .exceptions import ImdbAPIError  # noqa
+from .facade import ImdbFacade  # noqa

imdbpie/auth.py

@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+from __future__ import absolute_import, unicode_literals
+
+import json
+import tempfile
+from datetime import datetime
+from urllib.parse import urlparse, parse_qs
+import diskcache_community
+import requests
+from botocore.auth import SigV4Auth
+from botocore.awsrequest import AWSRequest
+from botocore.credentials import Credentials
+from dateutil.parser import parse
+from dateutil.tz import tzutc
+
+from .constants import APP_KEY, HOST, USER_AGENT, BASE_URI
+
+
+def _get_credentials():
+    url = '{0}/authentication/credentials/temporary/ios82'.format(BASE_URI)
+    response = requests.post(
+        url, json={'appKey': APP_KEY}, headers={'User-Agent': USER_AGENT}
+    )
+    response.raise_for_status()
+    return json.loads(response.content.decode('utf8'))['resource']
+
+
+class Auth(object):
+    SOON_EXPIRES_SECONDS = 60
+    _CREDS_STORAGE_KEY = 'imdbpie-credentials'
+
+    def __init__(self):
+        self._cachedir = tempfile.gettempdir()
+
+    def _cache(self):
+        return diskcache_community.Cache(
+            directory=self._cachedir,
+            disk=diskcache_community.SafeDisk.with_options(on_error='miss'),
+        )
+
+    def _get_creds(self):
+        with self._cache() as cache:
+            return cache.get(self._CREDS_STORAGE_KEY)
+
+    def _set_creds(self, creds):
+        with self._cache() as cache:
+            cache[self._CREDS_STORAGE_KEY] = creds
+        return creds
+
+    def clear_cached_credentials(self):
+        with self._cache() as cache:
+            cache.delete(self._CREDS_STORAGE_KEY)
+
+    def _creds_soon_expiring(self):
+        creds = self._get_creds()
+        if not creds:
+            return creds, True
+        expires_at = parse(creds['expirationTimeStamp'])
+        now = datetime.now(tzutc())
+        if now < expires_at:
+            time_diff = expires_at - now
+            if time_diff.total_seconds() < self.SOON_EXPIRES_SECONDS:
+                # creds will soon expire, so renew them
+                return creds, True
+            return creds, False
+        else:
+            return creds, True
+
+    def get_auth_headers(self, url_path):
+        creds, soon_expires = self._creds_soon_expiring()
+        if soon_expires:
+            creds = self._set_creds(creds=_get_credentials())
+        credentials = Credentials(
+            access_key=creds['accessKeyId'],
+            secret_key=creds['secretAccessKey'],
+            token=creds['sessionToken'],
+        )
+
+        parsed_url = urlparse(url_path)
+        params = {
+            key: val[0] for key, val in parse_qs(parsed_url.query).items()
+        }
+        req = requests.Request(
+            'GET',
+            f'https://{HOST}{parsed_url.path}',
+            params=params,
+            data='',
+            headers={},
+        )
+        prepared_request = req.prepare()
+        prepared_request.headers['User-Agent'] = USER_AGENT
+        aws_request = AWSRequest(
+            method=prepared_request.method,
+            url=prepared_request.url,
+            data=prepared_request.body,
+            headers=prepared_request.headers,
+        )
+        SigV4Auth(credentials, 'imdbapi', 'us-east-1').add_auth(aws_request)
+        return aws_request.prepare().headers

imdbpie/constants.py

@@ -0,0 +1,8 @@
+# -*- coding: utf-8 -*-
+from __future__ import absolute_import, unicode_literals
+
+HOST = 'api.imdbws.com'
+BASE_URI = 'https://{0}'.format(HOST)
+SEARCH_BASE_URI = 'https://v2.sg.media-imdb.com'
+USER_AGENT = 'IMDb/8.3.1 (iPhone9,4; iOS 11.2.1)'
+APP_KEY = '76a6cc20-6073-4290-8a2c-951b4580ae4a'

imdbpie/exceptions.py

@@ -0,0 +1,3 @@
+# -*- coding: utf-8 -*-
+class ImdbAPIError(Exception):
+    pass

imdbpie/facade.py

@@ -0,0 +1,430 @@
+# -*- coding: utf-8 -*-
+from __future__ import absolute_import, unicode_literals
+
+import re
+
+from dateutil.parser import parse
+
+from .imdbpie import Imdb
+from .objects import (
+    Award,
+    FilmingLocation,
+    Image,
+    Name,
+    NameSearchResult,
+    Title,
+    TitleBusiness,
+    TitleCertificate,
+    TitleEpisodes,
+    TitleName,
+    TitleRelease,
+    TitleSearchResult,
+    TitleVideo,
+    WatchOption,
+)
+
+REGEX_IMDB_ID = re.compile(r'([a-zA-Z]{2}[0-9]{7,8})')
+
+
+class ImdbFacade(object):
+    def __init__(self, client=None):
+        self._client = client or Imdb()
+
+    def get_title(self, imdb_id):
+        title_data, title_aux_data = self._get_title_data(imdb_id=imdb_id)
+        try:
+            runtime = title_aux_data['runningTimes'][0]['timeMinutes']
+        except (KeyError, IndexError):
+            runtime = None
+        try:
+            episodes = TitleEpisodes(facade=self, imdb_id=imdb_id)
+        except LookupError:
+            episodes = ()
+        try:
+            season = title_aux_data['season']
+            episode = title_aux_data['episode']
+        except KeyError:
+            season = None
+            episode = None
+        return Title(
+            season=season,
+            episode=episode,
+            episodes=episodes,
+            runtime=runtime,
+            **title_data
+        )
+
+    def get_name(self, imdb_id):
+        name_data = self._client.get_name(imdb_id=imdb_id)
+        base = name_data['base']
+        name = base['name']
+        imdb_id = self._parse_id(base['id'])
+
+        try:
+            image_data = base['image']
+            image = Image(
+                url=image_data['url'],
+                height=image_data['height'],
+                width=image_data['width'],
+            )
+        except KeyError:
+            image = None
+
+        gender = (base.get('gender') or '').lower() or None
+        birth_date = base.get('birthDate')
+        date_of_birth = parse(birth_date).date() if birth_date else None
+        birth_place = base.get('birthPlace')
+        try:
+            bios = tuple(b['text'] for b in base['miniBios'])
+        except KeyError:
+            bios = ()
+
+        filmography_data = self._client.get_name_filmography(imdb_id)
+        filmography = tuple(
+            self._parse_id(f['id']) for f in filmography_data['filmography']
+        )
+        known_for = tuple(
+            self._parse_id(item['id'])
+            for item in (name_data.get('knownFor') or ())
+            if item.get('id')
+        )
+        return Name(
+            name=name,
+            imdb_id=imdb_id,
+            date_of_birth=date_of_birth,
+            gender=gender,
+            birth_place=birth_place,
+            bios=bios,
+            image=image,
+            filmography=filmography,
+            jobs=tuple(name_data.get('jobs') or ()),
+            known_for=known_for,
+            real_name=base.get('realName'),
+            height_centimeters=base.get('heightCentimeters'),
+        )
+
+    def search_for_name(self, query):
+        results = []
+        for result in self._client.search_for_name(query):
+            result = NameSearchResult(
+                imdb_id=result['imdb_id'],
+                name=result['name'],
+            )
+            results.append(result)
+        return tuple(results)
+
+    def search_for_title(self, query):
+        results = []
+        for result in self._client.search_for_title(query):
+            if result['year']:
+                year = int(result['year'])
+            else:
+                year = None
+            result = TitleSearchResult(
+                imdb_id=result['imdb_id'],
+                title=result['title'],
+                type=result['type'],
+                year=year,
+            )
+            results.append(result)
+        return tuple(results)
+
+    def _get_writers(self, top_crew_data):
+        return tuple(
+            TitleName(
+                name=i['name'],
+                job=i.get('job'),
+                category=i.get('category'),
+                imdb_id=self._parse_id(i['id']),
+            )
+            for i in top_crew_data['writers']
+        )
+
+    def _get_stars(self, principals_data):
+        return tuple(
+            TitleName(
+                name=i['name'],
+                job=i.get('job'),
+                characters=tuple(i.get('characters', ())),
+                category=i.get('category'),
+                imdb_id=self._parse_id(i['id']),
+            )
+            for i in principals_data
+        )
+
+    def _get_creators(self, top_crew_data):
+        return tuple(
+            TitleName(
+                name=i['name'],
+                job=i.get('job'),
+                category=i.get('category'),
+                imdb_id=self._parse_id(i['id']),
+            )
+            for i in top_crew_data['writers']
+            if i.get('job') == 'creator'
+        )
+
+    def _get_directors(self, top_crew_data):
+        return tuple(
+            TitleName(
+                name=i['name'],
+                job=i.get('job'),
+                category=i.get('category'),
+                imdb_id=self._parse_id(i['id']),
+            )
+            for i in top_crew_data['directors']
+        )
+
+    def _get_credits(self, credits_data):
+        credits = []
+        for category in credits_data.get('credits', ()):
+            for item in credits_data['credits'][category]:
+                credits.append(
+                    TitleName(
+                        name=item['name'],
+                        category=item.get('category'),
+                        job=item.get('job'),
+                        imdb_id=self._parse_id(item['id']),
+                    )
+                )
+        return tuple(credits)
+
+    def _parse_id(self, string):
+        match = REGEX_IMDB_ID.search(string or '')
+        if not match:
+            raise ValueError('invalid imdb id: {0!r}'.format(string))
+        return match.group(1)
+
+    def _get_title_data(self, imdb_id):
+        base_title_data = self._client.get_title(imdb_id=imdb_id)
+        top_crew_data = self._client.get_title_top_crew(imdb_id=imdb_id)
+        title_aux_data = self._client.get_title_auxiliary(imdb_id=imdb_id)
+        credits_data = self._client.get_title_credits(imdb_id=imdb_id)
+
+        title = base_title_data['base']['title']
+        year = base_title_data['base'].get('year')
+        try:
+            rating = float(base_title_data['ratings']['rating'])
+        except KeyError:
+            rating = None
+        type_ = base_title_data['base']['titleType'].lower()
+
+        try:
+            releases_data = self._client.get_title_releases(imdb_id=imdb_id)
+        except LookupError:
+            release_date = None
+            releases = ()
+        else:
+            release_date = parse(releases_data['releases'][0]['date']).date()
+            releases = tuple(
+                TitleRelease(date=parse(r['date']).date(), region=r['region'])
+                for r in releases_data['releases']
+            )
+
+        try:
+            rating_count = base_title_data['ratings']['ratingCount']
+        except KeyError:
+            rating_count = 0
+
+        try:
+            plot_outline = base_title_data['plot']['outline']['text']
+        except KeyError:
+            plot_outline = None
+
+        writers = self._get_writers(top_crew_data)
+        directors = self._get_directors(top_crew_data)
+        creators = self._get_creators(top_crew_data)
+        try:
+            genres = tuple(g.lower() for g in title_aux_data.get('genres'))
+        except TypeError:
+            genres = ()
+        credits = self._get_credits(credits_data)
+
+        try:
+            certification = title_aux_data['certificate']['certificate']
+        except (KeyError, TypeError):
+            certification = None
+        stars = self._get_stars(title_aux_data['principals'])
+        try:
+            image_data = title_aux_data['image']
+            image = Image(
+                url=image_data['url'],
+                height=image_data['height'],
+                width=image_data['width'],
+            )
+        except KeyError:
+            image = None
+        metacritic_info = title_aux_data.get('metacriticInfo') or {}
+        certificate_data = title_aux_data.get('certificate') or {}
+        return (
+            dict(
+                imdb_id=imdb_id,
+                title=title,
+                year=year,
+                rating=rating,
+                type=type_,
+                release_date=release_date,
+                releases=releases,
+                plot_outline=plot_outline,
+                rating_count=rating_count,
+                writers=writers,
+                directors=directors,
+                creators=creators,
+                genres=genres,
+                credits=credits,
+                certification=certification,
+                image=image,
+                stars=stars,
+                metacritic=metacritic_info.get('metaScore'),
+                awards_summary=title_aux_data.get('awards'),
+                spoken_languages=tuple(
+                    title_aux_data.get('spokenLanguages') or ()
+                ),
+                countries=tuple(title_aux_data.get('origins') or ()),
+                alternate_titles=tuple(
+                    title_aux_data.get('alternateTitlesSample') or ()
+                ),
+                alternate_titles_count=(
+                    title_aux_data.get('alternateTitlesCount') or 0
+                ),
+                top_rank=title_aux_data.get('topRank'),
+                trailer=self._parse_trailer(title_aux_data.get('videos')),
+                production_status=title_aux_data.get('productionStatus'),
+                certificate_reason=certificate_data.get('ratingReason'),
+            ),
+            title_aux_data,
+        )
+
+    @staticmethod
+    def _parse_trailer(videos_data):
+        trailer = (videos_data or {}).get('mainTrailer')
+        if not trailer:
+            return None
+        url = None
+        for encoding in trailer.get('encodings') or ():
+            if encoding.get('play'):
+                url = encoding['play']
+                break
+        return TitleVideo(
+            content_type=trailer.get('contentType'),
+            description=trailer.get('description'),
+            url=url,
+            duration_seconds=trailer.get('durationSeconds'),
+        )
+
+    def get_title_watch_options(self, imdb_id):
+        data = self._client.get_title_watch_options(imdb_id=imdb_id)
+        options = []
+        for group in data.get('optionGroups') or ():
+            category = (group.get('displayName') or '').lower()
+            for option in group.get('watchOptions') or ():
+                link = option.get('link') or {}
+                provider = option.get('provider') or {}
+                options.append(
+                    WatchOption(
+                        provider=option.get('primaryText'),
+                        category=category,
+                        url=link.get('uri'),
+                        provider_id=provider.get('providerId'),
+                        notes=option.get('secondaryText'),
+                    )
+                )
+        return tuple(options)
+
+    def get_title_business(self, imdb_id):
+        data = self._client.get_title_business(imdb_id=imdb_id)
+        gross = data.get('gross') or {}
+        aggregations = gross.get('aggregations') or []
+        worldwide_gross = None
+        for aggregation in aggregations:
+            if aggregation.get('area') == 'World-wide':
+                worldwide_gross = aggregation.get('total')
+                break
+        opening_weekend = data.get('openingWeekendGross') or {}
+        return TitleBusiness(
+            budget=data.get('budget'),
+            worldwide_gross=worldwide_gross,
+            gross=tuple(gross.get('regional') or ()),
+            opening_weekend_gross=tuple(opening_weekend.get('regional') or ()),
+        )
+
+    def get_title_keywords(self, imdb_id):
+        data = self._client.get_title_keywords(imdb_id=imdb_id)
+        return tuple(data.get('keywords') or ())
+
+    def get_title_certificates(self, imdb_id):
+        data = self._client.get_title_certificates(imdb_id=imdb_id)
+        certificates = []
+        for country, entries in (data.get('certificates') or {}).items():
+            for entry in entries or ():
+                certificates.append(
+                    TitleCertificate(
+                        country=country,
+                        certificate=entry.get('certificate'),
+                        attributes=tuple(entry.get('attributes') or ()),
+                    )
+                )
+        return tuple(certificates)
+
+    def get_title_filming_locations(self, imdb_id):
+        data = self._client.get_title_filming_locations(imdb_id=imdb_id)
+        return tuple(
+            FilmingLocation(
+                location=item.get('location'),
+                attributes=tuple(item.get('attributes') or ()),
+                notes=tuple(item.get('extras') or ()),
+            )
+            for item in (data.get('locations') or ())
+        )
+
+    def get_title_crazy_credits(self, imdb_id):
+        data = self._client.get_title_crazy_credits(imdb_id=imdb_id)
+        return tuple(
+            item['text']
+            for item in (data.get('crazycredits') or ())
+            if item.get('text')
+        )
+
+    def get_title_principals(self, imdb_id):
+        data = self._client.get_title_principals(imdb_id=imdb_id)
+        return tuple(
+            TitleName(
+                name=item.get('name'),
+                category=item.get('category'),
+                imdb_id=(
+                    self._parse_id(item['id']) if item.get('id') else None
+                ),
+                job=item.get('job'),
+                characters=tuple(item.get('characters') or ()),
+            )
+            for item in (data.get('principals') or ())
+        )
+
+    def get_name_known_for(self, imdb_id):
+        data = self._client.get_name_known_for(imdb_id=imdb_id)
+        return tuple(
+            self._parse_id(item['id'])
+            for item in (data.get('knownFor') or ())
+            if item.get('id')
+        )
+
+    def get_name_awards(self, imdb_id):
+        data = self._client.get_name_awards(imdb_id=imdb_id)
+        awards = []
+        for item in data.get('awards') or ():
+            titles = (item.get('nominations') or {}).get('titles') or ()
+            awards.append(
+                Award(
+                    name=item.get('awardName'),
+                    category=item.get('category'),
+                    year=item.get('year'),
+                    won=bool(item.get('isWinner')),
+                    event_name=item.get('eventName'),
+                    title_ids=tuple(
+                        self._parse_id(title['id'])
+                        for title in titles
+                        if title.get('id')
+                    ),
+                )
+            )
+        return tuple(awards)

imdbpie/imdbpie.py

@@ -0,0 +1,430 @@
+# -*- coding: utf-8 -*-
+from __future__ import absolute_import, unicode_literals
+
+import copy
+import re
+import json
+import time
+from datetime import date
+import tempfile
+import logging
+
+from text_unidecode import unidecode
+import requests
+from urllib.parse import urlencode, urljoin, quote
+from http import client as httplib
+
+from .constants import BASE_URI, SEARCH_BASE_URI
+from .auth import Auth
+from .exceptions import ImdbAPIError
+
+logger = logging.getLogger(__name__)
+
+# client method name -> api path
+_SIMPLE_GET_ENDPOINTS = {
+    'get_name_images': '/name/{imdb_id}/images',
+    'get_name_videos': '/name/{imdb_id}/videos',
+    'get_title_metacritic_reviews': '/title/{imdb_id}/metacritic',
+    'get_title_user_reviews': '/title/{imdb_id}/userreviews',
+    'get_title_videos': '/title/{imdb_id}/videos',
+    'get_title_images': '/title/{imdb_id}/images',
+    'get_title_companies': '/title/{imdb_id}/companies',
+    'get_title_technical': '/title/{imdb_id}/technical',
+    'get_title_trivia': '/title/{imdb_id}/trivia',
+    'get_title_goofs': '/title/{imdb_id}/goofs',
+    'get_title_soundtracks': '/title/{imdb_id}/soundtracks',
+    'get_title_news': '/title/{imdb_id}/news',
+    'get_title_plot': '/title/{imdb_id}/plot',
+    'get_title_plot_synopsis': '/title/{imdb_id}/plotsynopsis',
+    'get_title_plot_taglines': '/title/{imdb_id}/taglines',
+    'get_title_versions': '/title/{imdb_id}/versions',
+    'get_title_releases': '/title/{imdb_id}/releases',
+    'get_title_quotes': '/title/{imdb_id}/quotes',
+    'get_title_connections': '/title/{imdb_id}/connections',
+    'get_title_genres': '/title/{imdb_id}/genres',
+    'get_title_similarities': '/title/{imdb_id}/similarities',
+    'get_title_awards': '/title/{imdb_id}/awards',
+    'get_title_ratings': '/title/{imdb_id}/ratings',
+    'get_title_credits': '/title/{imdb_id}/fullcredits',
+    'get_title_keywords': '/title/{imdb_id}/keywords',
+    'get_title_certificates': '/title/{imdb_id}/certificates',
+    'get_title_business': '/title/{imdb_id}/business',
+    'get_title_watch_options': '/title/{imdb_id}/watchoptions',
+    'get_title_principals': '/title/{imdb_id}/principals',
+    'get_title_filming_locations': '/title/{imdb_id}/filminglocations',
+    'get_title_crazy_credits': '/title/{imdb_id}/crazycredits',
+    'get_name': '/name/{imdb_id}/fulldetails',
+    'get_name_filmography': '/name/{imdb_id}/filmography',
+    'get_name_known_for': '/name/{imdb_id}/knownfor',
+    'get_name_awards': '/name/{imdb_id}/awards',
+    'get_name_bio': '/name/{imdb_id}/bio',
+    'get_name_trivia': '/name/{imdb_id}/trivia',
+    'get_name_quotes': '/name/{imdb_id}/quotes',
+    'get_name_news': '/name/{imdb_id}/news',
+}
+
+
+class Imdb(Auth):
+    CACHE_MAX_ENTRIES = 128
+
+    def __init__(
+        self,
+        locale=None,
+        exclude_episodes=False,
+        session=None,
+        cache_ttl=300,
+    ):
+        super().__init__()
+        self.locale = locale or 'en_US'
+        self.region = self.locale.split('_')[-1].upper()
+        self.exclude_episodes = exclude_episodes
+        self.session = session or requests.Session()
+        self._cachedir = tempfile.gettempdir()
+        self.cache_ttl = cache_ttl
+        self._resource_cache = {}
+
+    def __getattr__(self, name):
+        if name in _SIMPLE_GET_ENDPOINTS:
+            return self._simple_get_method(
+                method=name, path=_SIMPLE_GET_ENDPOINTS[name]
+            )
+        else:
+            msg = '{obj!r} object has no attribute {name!r}'.format(
+                obj=self.__class__.__name__,
+                name=name,
+            )
+            raise AttributeError(msg)
+
+    def get_title(self, imdb_id):
+        logger.info('called get_title %s', imdb_id)
+        self.validate_imdb_id(imdb_id)
+        # redirection check using API response
+        self._redirection_title_check(imdb_id)
+        try:
+            resource = self._get_resource_cached(
+                '/title/{0}/auxiliary'.format(imdb_id)
+            )
+        except LookupError:
+            self._title_not_found()
+
+        if (
+            self.exclude_episodes is True
+            and resource['base']['titleType'] == 'tvEpisode'
+        ):
+            raise LookupError(
+                'Title not found. Title was an episode and '
+                '"exclude_episodes" is set to true'
+            )
+        return resource
+
+    def _fetch_title_auxiliary(self, imdb_id):
+        path = '/template/imdb-ios-writable/title-auxiliary-v31.jstl/render'
+        return self._get_cached(
+            url=urljoin(BASE_URI, path),
+            params={
+                'inlineBannerAdWeblabOn': 'false',
+                'minwidth': '320',
+                'osVersion': '11.3.0',
+                'region': self.region,
+                'tconst': imdb_id,
+                'today': date.today().strftime('%Y-%m-%d'),
+            },
+        )
+
+    def get_title_auxiliary(self, imdb_id):
+        logger.info('called get_title_auxiliary %s', imdb_id)
+        self.validate_imdb_id(imdb_id)
+        # redirection check using API response
+        self._redirection_title_check(imdb_id)
+        try:
+            resource = self._fetch_title_auxiliary(imdb_id)
+        except LookupError:
+            self._title_not_found()
+
+        if (
+            self.exclude_episodes is True
+            and resource['titleType'].lower() == 'tvepisode'
+        ):
+            raise LookupError(
+                'Title not found. Title was an episode and '
+                '"exclude_episodes" is set to true'
+            )
+        return resource
+
+    def _simple_get_method(self, method, path):
+        """Return client method generated from ``_SIMPLE_GET_ENDPOINTS``."""
+
+        def get(imdb_id):
+            logger.info('called %s %s', method, imdb_id)
+            self.validate_imdb_id(imdb_id)
+            self._redirection_title_check(imdb_id)
+            return self._get_resource(path.format(imdb_id=imdb_id))
+
+        return get
+
+    def title_exists(self, imdb_id):
+        self.validate_imdb_id(imdb_id)
+        try:
+            self._get_resource('/title/{0}/auxiliary'.format(imdb_id))
+            return True
+        except LookupError:
+            return False
+
+    def _suggest_search(self, query):
+        # translates national characters into similar sounding latin characters
+        cleaned_query = unidecode(query)
+        query_encoded = quote(cleaned_query)
+        first_alphanum_char = self._query_first_alpha_num(cleaned_query)
+        path = '/suggests/{0}/{1}.json'.format(
+            first_alphanum_char, query_encoded
+        )
+        url = urljoin(SEARCH_BASE_URI, path)
+        search_results = self._get(url=url, query=query_encoded)
+        return search_results
+
+    def search_for_name(self, name):
+        logger.info('called search_for_name %s', name)
+        name = re.sub(r'\W+', '+', name).strip('+')
+        search_results = self._suggest_search(name)
+        results = []
+        for result in search_results.get('d', ()):
+            if not result['id'].startswith('nm'):
+                # ignore non-person results
+                continue
+            result_item = {
+                'name': result['l'],
+                'imdb_id': result['id'],
+            }
+            results.append(result_item)
+        return results
+
+    def search_for_title(self, title):
+        logger.info('called search_for_title %s', title)
+        title = re.sub(r'\W+', '+', title).strip('+')
+        search_results = self._suggest_search(title)
+        results = []
+        for result in search_results.get('d', ()):
+            if not result['id'].startswith('tt'):
+                # ignore non-title results
+                continue
+            result_item = {
+                'title': result['l'],
+                'year': str(result['y']) if result.get('y') else None,
+                'imdb_id': result['id'],
+                'type': result.get('q'),
+            }
+            results.append(result_item)
+        return results
+
+    def get_popular_titles(self):
+        return self._get_resource('/chart/titlemeter')
+
+    def get_popular_shows(self):
+        return self._get_resource('/chart/tvmeter')
+
+    def get_popular_movies(self):
+        return self._get_resource('/chart/moviemeter')
+
+    def get_title_episodes(self, imdb_id):
+        logger.info('called get_title_episodes %s', imdb_id)
+        self.validate_imdb_id(imdb_id)
+        if self.exclude_episodes:
+            raise ValueError('exclude_episodes is current set to true')
+        return self._get_resource('/title/{0}/episodes'.format(imdb_id))
+
+    def get_title_episodes_detailed(
+        self, imdb_id, season, limit=500, region=None, offset=0
+    ):
+        """
+        Request detailed information for a tv series, for a specific season.
+
+        :param imdb_id: The imdb id including the TT prefix.
+        :param limit: Limit the amound of episodes returned for a season.
+        :param region: Two capital letter region code in ISO 3166-1 alpha-2.
+        :param season: The season you want the detailed information for.
+        :param offset: Offset episode results by this value.
+        """
+        logger.info('called get_title_episodes_detailed %s', imdb_id)
+        self.validate_imdb_id(imdb_id)
+        if season < 1:
+            raise ValueError('season must be greater than zero')
+        params = {
+            'end': limit,
+            'start': offset,
+            'season': season - 1,  # api seasons are zero indexed
+            'tconst': imdb_id,
+        }
+        if region:
+            params.update({'region': region})
+
+        return self._get(
+            urljoin(
+                BASE_URI,
+                '/template/imdb-ios-writable/tv-episodes-v2.jstl/render',
+            ),
+            params=params,
+        )
+
+    def get_title_top_crew(self, imdb_id):
+        """
+        Request detailed information about title's top crew
+        (ie: directors, writters, etc.).
+
+        :param imdb_id: The imdb id including the TT prefix.
+        """
+        logger.info('called get_title_top_crew %s', imdb_id)
+        self.validate_imdb_id(imdb_id)
+        params = {'tconst': imdb_id}
+        return self._get(
+            urljoin(
+                BASE_URI,
+                '/template/imdb-android-writable/7.3.top-crew.jstl/render',
+            ),
+            params=params,
+        )
+
+    @staticmethod
+    def _parse_dirty_json(data, query=None):
+        if query is None:
+            match_json_within_dirty_json = r'imdb\$.+\({1}(.+)\){1}'
+        else:
+            # No need to unquote as the json is containing quoted query
+            match_json_within_dirty_json = r'imdb\${}\((.+)\)'.format(query)
+        data_clean = re.match(
+            match_json_within_dirty_json, data, re.IGNORECASE
+        ).groups()[0]
+        return json.loads(data_clean)
+
+    @staticmethod
+    def validate_imdb_id(imdb_id):
+        match_id = r'[a-zA-Z]{2}[0-9]{7,8}'
+        try:
+            re.match(match_id, imdb_id, re.IGNORECASE).group()
+        except (AttributeError, TypeError):
+            raise ValueError('invalid imdb id')
+
+    @staticmethod
+    def _is_redirection_result(response):
+        """
+        Return True if response is that of a redirection else False
+        Redirection results have no information of use.
+        """
+        imdb_id = response['data'].get('tconst')
+        if imdb_id and imdb_id != response['data'].get('news', {}).get(
+            'channel'
+        ):
+            return True
+        return False
+
+    def _get_resource(self, path):
+        url = urljoin(BASE_URI, path)
+        return self._get(url=url)['resource']
+
+    def _get_resource_cached(self, path):
+        url = urljoin(BASE_URI, path)
+        return self._get_cached(url=url)['resource']
+
+    def clear_cache(self):
+        """Drop resources cached by this client instance."""
+        self._resource_cache.clear()
+
+    def _evict_cache(self, now):
+        for key, (expires_at, _) in list(self._resource_cache.items()):
+            if expires_at <= now:
+                del self._resource_cache[key]
+        while len(self._resource_cache) >= self.CACHE_MAX_ENTRIES:
+            oldest = next(iter(self._resource_cache))
+            del self._resource_cache[oldest]
+
+    def _get_cached(self, url, params=None):
+        """``_get`` with a ``cache_ttl`` second memory cache."""
+        if not self.cache_ttl:
+            return self._get(url=url, params=params)
+        key = (url, tuple(sorted((params or {}).items())))
+        cached = self._resource_cache.get(key)
+        now = time.monotonic()
+        if cached is not None and cached[0] > now:
+            # Hand out a copy so callers cannot mutate the cached payload.
+            return copy.deepcopy(cached[1])
+        resource = self._get(url=url, params=params)
+        if resource is not None:
+            # Do not cache error responses, they clear up on the next call.
+            self._evict_cache(now)
+            self._resource_cache[key] = (
+                now + self.cache_ttl,
+                copy.deepcopy(resource),
+            )
+        return resource
+
+    def _get(self, url, query=None, params=None):
+        headers = {'Accept-Language': self.locale}
+        if params:
+            full_url = '{0}?{1}'.format(url, urlencode(params))
+        else:
+            full_url = url
+        headers.update(self.get_auth_headers(full_url))
+        resp = self.session.get(url, headers=headers, params=params)
+        if not resp.ok:
+            if resp.status_code == httplib.NOT_FOUND:
+                raise LookupError('Resource {0} not found'.format(url))
+            else:
+                msg = '{0} {1}'.format(resp.status_code, resp.text)
+                raise ImdbAPIError(msg)
+        resp_data = resp.content.decode('utf-8')
+        try:
+            resp_dict = json.loads(resp_data)
+        except ValueError:
+            resp_dict = self._parse_dirty_json(data=resp_data, query=query)
+
+        if resp_dict.get('error'):
+            return None
+        return resp_dict
+
+    def _redirection_title_check(self, imdb_id):
+        if self.is_redirection_title(imdb_id):
+            self._title_not_found(
+                msg='{0} is a redirection imdb id'.format(imdb_id)
+            )
+
+    def is_redirection_title(self, imdb_id):
+        self.validate_imdb_id(imdb_id)
+        try:
+            if imdb_id.startswith('nm'):
+                resource = self._get_resource_cached(
+                    '/name/{0}/fulldetails'.format(imdb_id)
+                )
+                returned_id = resource['base'].get('id', '')
+                if returned_id:
+                    match = re.search(r'nm\d{7,8}', returned_id)
+                    if match:
+                        actual_id = match.group()
+                        # If the returned ID differs, it's a redirection
+                        return actual_id != imdb_id
+            else:
+                resource = self._fetch_title_auxiliary(imdb_id)
+                returned_id = resource.get('id', '')
+                if returned_id:
+                    match = re.search(r'tt\d{7,8}', returned_id)
+                    if match:
+                        actual_id = match.group()
+                        # If the returned ID differs, it's a redirection
+                        return actual_id != imdb_id
+            return False
+        except LookupError:
+            # If ID doesn't exist at all, it's not a redirection
+            return False
+
+    @staticmethod
+    def _query_first_alpha_num(query):
+        for char in query.lower():
+            if char.isalnum():
+                return char
+        raise ValueError(
+            'invalid query, does not contain any alphanumeric characters'
+        )
+
+    @staticmethod
+    def _title_not_found(msg=''):
+        if msg:
+            msg = ' {0}'.format(msg)
+        raise LookupError('Title not found.{0}'.format(msg))

imdbpie/objects.py

@@ -0,0 +1,162 @@
+import attr
+
+
+@attr.s
+class Image(object):
+    url = attr.ib()
+    width = attr.ib()
+    height = attr.ib()
+
+
+@attr.s
+class TitleVideo(object):
+    content_type = attr.ib(default=None)
+    description = attr.ib(default=None)
+    url = attr.ib(default=None)
+    duration_seconds = attr.ib(default=None)
+
+
+@attr.s
+class WatchOption(object):
+    provider = attr.ib()
+    category = attr.ib()
+    url = attr.ib(default=None)
+    provider_id = attr.ib(default=None)
+    notes = attr.ib(default=None)
+
+
+@attr.s
+class TitleBusiness(object):
+    budget = attr.ib(default=None)
+    worldwide_gross = attr.ib(default=None)
+    gross = attr.ib(default=())
+    opening_weekend_gross = attr.ib(default=())
+
+
+@attr.s
+class TitleCertificate(object):
+    country = attr.ib()
+    certificate = attr.ib()
+    attributes = attr.ib(default=())
+
+
+@attr.s
+class FilmingLocation(object):
+    location = attr.ib()
+    attributes = attr.ib(default=())
+    notes = attr.ib(default=())
+
+
+@attr.s
+class Award(object):
+    name = attr.ib()
+    category = attr.ib()
+    year = attr.ib(default=None)
+    won = attr.ib(default=False)
+    event_name = attr.ib(default=None)
+    title_ids = attr.ib(default=())
+
+
+class TitleEpisodes(object):
+    def __init__(self, facade, imdb_id):
+        self._facade = facade
+        episodes = self._facade._client.get_title_episodes(imdb_id=imdb_id)
+        self._episode_imdb_ids = []
+        for season in episodes['seasons']:
+            for episode in season['episodes']:
+                imdb_id = self._facade._parse_id(episode['id'])
+                self._episode_imdb_ids.append(imdb_id)
+        self._count = len(self._episode_imdb_ids)
+
+    def __len__(self):
+        return self._count
+
+    def __bool__(self):
+        return self._count > 0
+
+    def __getitem__(self, index):
+        imdb_id = self._episode_imdb_ids[index]
+        return self._facade.get_title(imdb_id=imdb_id)
+
+
+@attr.s
+class Title(object):
+    imdb_id = attr.ib()
+    title = attr.ib()
+    type = attr.ib()
+    certification = attr.ib()
+    year = attr.ib()
+    genres = attr.ib()
+    writers = attr.ib()
+    creators = attr.ib()
+    credits = attr.ib()
+    directors = attr.ib()
+    stars = attr.ib()
+    image = attr.ib()
+    episodes = attr.ib()
+    rating_count = attr.ib(default=0)
+    releases = attr.ib(default=())
+    season = attr.ib(default=None)
+    episode = attr.ib(default=None)
+    rating = attr.ib(default=None)
+    plot_outline = attr.ib(default=None)
+    release_date = attr.ib(default=None)
+    runtime = attr.ib(default=None)
+    metacritic = attr.ib(default=None)
+    awards_summary = attr.ib(default=None)
+    spoken_languages = attr.ib(default=())
+    countries = attr.ib(default=())
+    alternate_titles = attr.ib(default=())
+    alternate_titles_count = attr.ib(default=0)
+    top_rank = attr.ib(default=None)
+    trailer = attr.ib(default=None)
+    production_status = attr.ib(default=None)
+    certificate_reason = attr.ib(default=None)
+
+    def __repr__(self):
+        return 'Title(imdb_id={0}, title={1})'.format(self.imdb_id, self.title)
+
+
+@attr.s
+class TitleSearchResult(object):
+    imdb_id = attr.ib()
+    title = attr.ib()
+    type = attr.ib()
+    year = attr.ib()
+
+
+@attr.s
+class NameSearchResult(object):
+    imdb_id = attr.ib()
+    name = attr.ib()
+
+
+@attr.s
+class TitleRelease(object):
+    date = attr.ib()
+    region = attr.ib()
+
+
+@attr.s
+class TitleName(object):
+    name = attr.ib()
+    category = attr.ib()
+    imdb_id = attr.ib()
+    job = attr.ib(default=None)
+    characters = attr.ib(default=())
+
+
+@attr.s
+class Name(object):
+    name = attr.ib()
+    imdb_id = attr.ib()
+    image = attr.ib()
+    birth_place = attr.ib()
+    gender = attr.ib()
+    bios = attr.ib()
+    date_of_birth = attr.ib()
+    filmography = attr.ib()
+    jobs = attr.ib(default=())
+    known_for = attr.ib(default=())
+    real_name = attr.ib(default=None)
+    height_centimeters = attr.ib(default=None)

imdbpie-5.8.0.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: imdbpie
+Version: 5.8.0
+Summary: Python IMDB client using the IMDB json web service made available for their iOS app.
+Author-email: Richard O'Dwyer <richard@richard.do>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://code.richard.do/richardARPANET/imdb-pie/
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: attrs>=26.1.0
+Requires-Dist: boto>=2.49.0
+Requires-Dist: botocore>=1.42.83
+Requires-Dist: diskcache-community>=5.8.3
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: requests>=2.33.1
+Requires-Dist: setuptools>=82.0.1
+Requires-Dist: text-unidecode>=1.3
+Requires-Dist: wheel>=0.46.3
+Dynamic: license-file
+
+ImdbPie
+=======
+
+|PyPI| |Python Versions|
+
+Python IMDB client using the IMDB JSON web service made available for their iOS application.
+
+API Terminology
+---------------
+
+-  ``Title`` this can be a movie, tv show, video, documentary etc.
+-  ``Name`` this can be a credit, cast member, any person generally.
+
+Installation
+------------
+
+To install imdbpie, simply:
+
+.. code:: bash
+
+    uv add imdbpie
+
+How to use
+------------
+
+Choose an option:
+
+1. `ImdbPie Facade usage examples <FACADE.rst>`_ (the easy way, returns objects).
+
+2. `ImdbPie Client usage examples <CLIENT.rst>`_ (more low level client API, returns raw dicts).
+
+Requirements
+------------
+
+::
+
+    1. Python 3.10 or newer
+    2. Dependencies are declared in pyproject.toml and pinned in uv.lock
+
+Development
+-----------
+
+This project uses `uv <https://docs.astral.sh/uv/>`_ for environments,
+dependencies and locking.
+
+.. code:: bash
+
+    uv sync
+
+Running the tests
+-----------------
+
+.. code:: bash
+
+    uv run pytest src/tests
+
+Some tests call the live IMDb API and are marked ``live``. Skip them when
+working offline:
+
+.. code:: bash
+
+    uv run pytest src/tests -m "not live"
+
+.. |PyPI| image:: https://img.shields.io/pypi/v/imdbpie.svg
+   :target: https://pypi.python.org/pypi/imdb-pie
+.. |Python Versions| image:: https://img.shields.io/pypi/pyversions/imdbpie.svg
+   :target: https://pypi.python.org/pypi/imdb-pie

imdbpie-5.8.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+imdbpie/__init__.py,sha256=q4MdNaE0WwCfodXbYENvHnpHNAwbXTruLHF6lq_E97c,142
+imdbpie/auth.py,sha256=IwPeYfacjZC2HqhRe41VN7XtWBjl_CwTIFAph6a9OdY,3190
+imdbpie/constants.py,sha256=26DT7y1jKwI_eVuVyjL6js9IN2OxYGxkAsF4Gzr8Gb0,292
+imdbpie/exceptions.py,sha256=gmYjoIWWd7kQGlIGHKO00261ElQDEo-pnZ1tXXvX4kM,64
+imdbpie/facade.py,sha256=74Qkdds2Qp-Oir1Eye5DjmdUUqDWOnWeCvw0vYbQuDk,14861
+imdbpie/imdbpie.py,sha256=pFBt251C554d0sD96jM5YoqGThXDLnIl-rPZul22ylQ,15819
+imdbpie/objects.py,sha256=P_0rbO8EFSYh1LCozfL30-yJCI2AoiB5H1X9ptRDAeg,3908
+imdbpie-5.8.0.dist-info/licenses/LICENSE,sha256=i42eLltK2Nu2C2HUnml4JMKcAz582pLMyxeOShb70Sg,583
+imdbpie-5.8.0.dist-info/METADATA,sha256=KA4U4kAGHme6iMV1xY3DJODSjPSJtVVIxB6iahIEIqU,2317
+imdbpie-5.8.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+imdbpie-5.8.0.dist-info/top_level.txt,sha256=FPdYez0bUsp6xnEuNFanitCDlm6gO11optSdUfQk4wE,8
+imdbpie-5.8.0.dist-info/RECORD,,

imdbpie-5.8.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

imdbpie-5.8.0.dist-info/licenses/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2017 Richard O'Dwyer
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

imdbpie-5.8.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+imdbpie