spotifywebapiPython 1.0.97__py3-none-any.whl → 1.0.99__py3-none-any.whl

spotifywebapipython/models/playerplaystate.py

@@ -28,6 +28,7 @@ class PlayerPlayState:
         """
         self._Actions:PlayerActions = None
         self._Context:Context = None
+        self._ItemType:str = None
         self._CurrentlyPlayingType:str = None
         self._Device:Device = None
         self._Item:object = None
@@ -148,6 +149,27 @@ class PlayerPlayState:
         return self._Item
 
 
+    @property
+    def ItemType(self) -> str:
+        """ 
+        The type of the currently playing episode; can be null.  
+        This value will be null if the `Item` property value is null.
+        
+        If not null, it can be one of `audiobook` or `podcast`.
+        
+        Note that this is not a Spotify Web API property; it is loaded from our API so
+        that the type of episode can be determined programatically (e.g. audiobook or podcast).
+        """
+        return self._ItemType
+
+    @ItemType.setter
+    def ItemType(self, value:str):
+        """ 
+        Sets the ItemType property value.
+        """
+        self._ItemType = value
+
+
     @property
     def IsAdvertisement(self) -> bool:
         """ 
@@ -330,6 +352,7 @@ class PlayerPlayState:
             'shuffle_state': self._ShuffleState,
             'smart_shuffle': self._SmartShuffle,
             'timestamp': self._Timestamp,
+            'item_type': self._ItemType,
             'item': item,
         }
         return result
@@ -342,6 +365,7 @@ class PlayerPlayState:
         msg:str = 'PlayerPlayState:'
         #if self._Actions is not None: msg = '%s\n %s' % (msg, str(self._Actions))
         if self._CurrentlyPlayingType is not None: msg = '%s\n CurrentlyPlayingType="%s"' % (msg, str(self._CurrentlyPlayingType))
+        if self._ItemType is not None: msg = '%s\n ItemType="%s"' % (msg, str(self._ItemType))
         if self._Device is not None: msg = '%s\n Device Name="%s"' % (msg, str(self._Device.Name))
         #if self._Context is not None: msg = '%s\n %s' % (msg, str(self._Context))
         #if self._Item is not None: msg = '%s\n %s' % (msg, str(self._Item))

spotifywebapipython/spotifyapimessage.py

@@ -42,6 +42,7 @@ class SpotifyApiMessage:
         self._RequestHeaders:Mapping[str, str] = requestHeaders
         self._RequestJson:dict = None
         self._ResponseData = {}
+        self._IgnoreResponseErrors:bool = False
         self._IsRequestDataEncoded:bool = False
         self._Uri:str = uri
         self._UrlParameters:dict = urlParameters
@@ -99,6 +100,22 @@ class SpotifyApiMessage:
         return self._RequestData is not None
 
 
+    @property
+    def IgnoreResponseErrors(self) -> bool:
+        """ 
+        Indicates if request response errors are ignored (True) or not (False, default).  
+        If not, an exception will be thrown with the error details.
+        """
+        return self._IgnoreResponseErrors
+
+    @IgnoreResponseErrors.setter
+    def IgnoreResponseErrors(self, value:bool):
+        """ 
+        Sets the IgnoreResponseErrors property value.
+        """
+        self._IgnoreResponseErrors = value
+
+
     @property
     def IsRequestDataEncoded(self) -> bool:
         """ 
@@ -109,7 +126,7 @@ class SpotifyApiMessage:
     @IsRequestDataEncoded.setter
     def IsRequestDataEncoded(self, value:bool):
         """ 
-        Sets the MethodName property value.
+        Sets the IsRequestDataEncoded property value.
         """
         self._IsRequestDataEncoded = value
 

spotifywebapipython/spotifyclient.py

@@ -607,7 +607,8 @@ class SpotifyClient:
                     if errCode is None:
                         errCode = response.status
                         
-                    raise SpotifyWebApiError(errCode, errMessage, msg.MethodName, response.reason, _logsi)
+                    if (not msg.IgnoreResponseErrors):
+                        raise SpotifyWebApiError(errCode, errMessage, msg.MethodName, response.reason, _logsi)
 
                 elif isinstance(errObj, str):
                     
@@ -5216,6 +5217,7 @@ class SpotifyClient:
     def GetChapter(self, 
                    chapterId:str, 
                    market:str=None,
+                   ignoreResponseErrors:bool=False,
                    ) -> Chapter:
         """
         Get Spotify catalog information for a single audiobook chapter identified by its unique Spotify ID.
@@ -5234,6 +5236,9 @@ class SpotifyClient:
                 Note: If neither market or user country are provided, the content is considered unavailable for the client.  
                 Users can view the country that is associated with their account in the account settings.  
                 Example: `ES`
+            ignoreResponseErrors (bool):
+                True to ignore any request response errors that occur; otherwise, an exception will be thrown
+                if a response error is detected (default).
                 
         Returns:
             An `Chapter` object that contain the chapter details.
@@ -5267,6 +5272,7 @@ class SpotifyClient:
             apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
             apiMethodParms.AppendKeyValue("chapterId", chapterId)
             apiMethodParms.AppendKeyValue("market", market)
+            apiMethodParms.AppendKeyValue("ignoreResponseErrors", ignoreResponseErrors)
             _logsi.LogMethodParmList(SILevel.Verbose, "Get Spotify catalog information for a single audiobook chapter", apiMethodParms)
                 
             # ensure market was either supplied or implied; default if neither.
@@ -5281,6 +5287,7 @@ class SpotifyClient:
             msg:SpotifyApiMessage = SpotifyApiMessage(apiMethodName, '/chapters/{id}'.format(id=chapterId))
             msg.RequestHeaders[self.AuthToken.HeaderKey] = self.AuthToken.HeaderValue
             msg.UrlParameters = urlParms
+            msg.IgnoreResponseErrors = ignoreResponseErrors
             self.MakeRequest('GET', msg)
 
             # process results.
@@ -6760,6 +6767,17 @@ class SpotifyClient:
 
             # process results.
             result = PlayerPlayState(root=msg.ResponseData)
+            
+            # is this an episode?  if so, then determine the item type (e.g. podcast or audiobook).
+            if (result is not None):
+                if (result.Item is not None):
+                    result.ItemType = SpotifyClient.GetTypeFromUri(result.Item.Uri)
+                    if (result.CurrentlyPlayingType == 'episode'):
+                        uriId:str = SpotifyClient.GetIdFromUri(result.Item.Uri)
+                        if (self.IsChapterEpisode(uriId)):
+                            result.ItemType = 'audiobook'
+                        else:
+                            result.ItemType = 'podcast'
         
             # trace.
             _logsi.LogObject(SILevel.Verbose, TRACE_METHOD_RESULT_TYPE % (apiMethodName, type(result).__name__), result, excludeNonPublic=True)
@@ -6833,11 +6851,28 @@ class SpotifyClient:
         return result
     
 
-    def GetPlayerNowPlayingAudiobookUri(self) -> str:
+    def GetPlayerNowPlayingAudiobookUri(
+            self,
+            market:str=None,
+            ignoreResponseErrors:bool=False,
+            ) -> str:
         """
         Returns the audiobook uri value of the currently playing media if something is
         playing; otherwise, null is returned.
         
+        Args:
+            market (str):
+                An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that 
+                is available in that market will be returned.  If a valid user access token is specified 
+                in the request header, the country associated with the user account will take priority over 
+                this parameter.  
+                Note: If neither market or user country are provided, the content is considered unavailable for the client.  
+                Users can view the country that is associated with their account in the account settings.  
+                Example: `ES`
+            ignoreResponseErrors (bool):
+                True to ignore any request response errors that occur; otherwise, an exception will be thrown
+                if a response error is detected (default).
+                
         Raises:
             SpotifyApiError: 
                 If current user does not have a Spotify free or premium level account.  
@@ -6846,17 +6881,19 @@ class SpotifyClient:
         result:str = None
         
         # get nowplaying status.
-        nowPlaying:PlayerPlayState = self.GetPlayerNowPlaying(additionalTypes='episode')
+        nowPlaying:PlayerPlayState = self.GetPlayerNowPlaying(market, additionalTypes='episode')
         
         # is an chapter playing?  if so, return the parent show uri value.
         if nowPlaying is not None:
             if nowPlaying.CurrentlyPlayingType in ['episode']:
                 playingItem:Chapter = nowPlaying.Item
                 if (playingItem is not None):
-                    chapter:Chapter = self.GetChapter(playingItem.Id)
-                    result = chapter.Audiobook.Uri
+                    chapter:Chapter = self.GetChapter(playingItem.Id, market, ignoreResponseErrors)
+                    if (chapter.Audiobook is not None):
+                        result = chapter.Audiobook.Uri
             else:
-                raise SpotifyApiError("Currently playing item is not a Audiobook Chapter", logsi=_logsi)
+                if (not ignoreResponseErrors):
+                    raise SpotifyApiError("Currently playing item is not a Audiobook Chapter", logsi=_logsi)
                 
         return result
     
@@ -7035,7 +7072,18 @@ class SpotifyClient:
 
             # process results.
             result = PlayerPlayState(root=msg.ResponseData)
-
+            
+            # is this an episode?  if so, then determine the item type (e.g. podcast or audiobook).
+            if (result is not None):
+                if (result.Item is not None):
+                    result.ItemType = SpotifyClient.GetTypeFromUri(result.Item.Uri)
+                    if (result.CurrentlyPlayingType == 'episode'):
+                        uriId:str = SpotifyClient.GetIdFromUri(result.Item.Uri)
+                        if (self.IsChapterEpisode(uriId)):
+                            result.ItemType = 'audiobook'
+                        else:
+                            result.ItemType = 'podcast'
+        
             # check for a restricted device; if found, then grab the device id from the 
             # cached list of spotify connect devices (if present).
             if result is not None:
@@ -10523,6 +10571,97 @@ class SpotifyClient:
             _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
 
 
+    def IsChapterEpisode(
+            self, 
+            episodeId:str=None, 
+            market:str=None,
+            ) -> bool:
+        """
+        Returns true if the specified episode id is an audiobook chapter; otherwise, false.
+        
+        Args:
+            episodeId (str):  
+                The Spotify ID to check.
+                Example: `74aydHJKgYz3AIq3jjBSv1`
+                If null, the currently playing uri id value is used; a Spotify Free or Premium account 
+                is required to correctly read the currently playing context.
+            market (str):
+                An ISO 3166-1 alpha-2 country code. If a country code is specified, only content that 
+                is available in that market will be returned.  If a valid user access token is specified 
+                in the request header, the country associated with the user account will take priority over 
+                this parameter.  
+                Note: If neither market or user country are provided, the content is considered unavailable for the client.  
+                Users can view the country that is associated with their account in the account settings.  
+                Example: `ES`
+                
+        Returns:
+            True if the specified id is an audiobook chapter; otherwise, false.
+                
+        Raises:
+            SpotifyWebApiError: 
+                If the Spotify Web API request was for a non-authorization service 
+                and the response contains error information.
+            SpotifApiError: 
+                If the method fails for any other reason.
+
+        <details>
+          <summary>Sample Code</summary>
+        ```python
+        .. include:: ../docs/include/samplecode/SpotifyClient/IsChapterEpisode.py
+        ```
+          <summary>Sample Code - NowPlaying</summary>
+        ```python
+        .. include:: ../docs/include/samplecode/SpotifyClient/IsChapterEpisode_NowPlaying.py
+        ```
+        </details>
+        """
+        apiMethodName:str = 'IsChapterEpisode'
+        apiMethodParms:SIMethodParmListContext = None
+        result:bool = False
+        
+        try:
+            
+            # trace.
+            apiMethodParms = _logsi.EnterMethodParmList(SILevel.Debug, apiMethodName)
+            apiMethodParms.AppendKeyValue("episodeId", episodeId)
+            apiMethodParms.AppendKeyValue("market", market)
+            _logsi.LogMethodParmList(SILevel.Verbose, "Check if episode id is an audiobook chapter or not", apiMethodParms)
+                
+            # ensure market was either supplied or implied; default if neither.
+            market = self._ValidateMarket(market)
+
+            # if id not specified, then return currently playing id value.
+            # this will issue a GetChapter call to retrieve the actual audiobook id.
+            # the `GetPlayerNowPlayingAudiobookUri` method will fail if it's not a chapter id.
+            if (episodeId is None) or (len(episodeId.strip()) == 0):
+                
+                uri = self.GetPlayerNowPlayingAudiobookUri(market, True)
+                result = (uri is not None)
+                
+            else:
+                
+                # if id was supplied, then call the `GetChapter` method to retrieve chapter information.
+                # the `GetChapter` method will fail if it's not a chapter id.
+                chapter:Chapter = self.GetChapter(episodeId, market, True)
+                result = (chapter.Id is not None)
+                
+            return result
+
+        except Exception as ex:
+            
+            # at this point we can safely assume it's NOT an audiobook chapter.
+            result = False
+            return result
+               
+        finally:
+        
+            # trace.
+            _logsi.LogValue(SILevel.Verbose, TRACE_METHOD_RESULT % (apiMethodName), result)
+
+            # trace.
+            _logsi.LeaveMethod(SILevel.Debug, apiMethodName)
+
+
     @staticmethod
     def IsDeviceId(value:str) -> bool:
         """