spotify-apimatic-sdk 1.0.0__py3-none-any.whl

spotifywebapi/http/auth/o_auth_2.py

@@ -0,0 +1,336 @@
+
+"""
+spotifywebapi
+
+This file was automatically generated by APIMATIC v3.0 (
+ https://www.apimatic.io ).
+"""
+
+import os
+
+from apimatic_core.authentication.header_auth import (
+    HeaderAuth,
+)
+from apimatic_core.utilities.auth_helper import (
+    AuthHelper,
+)
+
+from spotifywebapi.api_helper import APIHelper
+from spotifywebapi.configuration import Server
+from spotifywebapi.controllers.o_auth_authorization_controller import (
+    OAuthAuthorizationController,
+)
+from spotifywebapi.models.o_auth_token import (
+    OAuthToken,
+)
+
+
+class OAuth2(HeaderAuth):
+    """
+    An authentication handler that applies `AuthorizationCodeAuth` to
+    outgoing requests. It constructs the required credential values and integrates
+    with the core authentication framework.
+    """
+
+    @property
+    def error_message(self):
+        """Return reason about the authentication failure."""
+        return "AuthorizationCodeAuth: OAuthToken is undefined or expired."
+
+    def __init__(self, auth_credentials_model, config):
+        """
+        Initialize the authentication handler with credential data.
+
+        Args:
+            auth_credentials_model: The credentials object used to generate
+                the authorization header.
+            config: The configuration instance.
+
+        """
+        self._o_auth_client_id = auth_credentials_model.o_auth_client_id \
+            if auth_credentials_model is not None else None
+        self._o_auth_client_secret = auth_credentials_model.o_auth_client_secret \
+            if auth_credentials_model is not None else None
+        self._o_auth_redirect_uri = auth_credentials_model.o_auth_redirect_uri \
+            if auth_credentials_model is not None else None
+        if auth_credentials_model is not None \
+                and isinstance(auth_credentials_model.o_auth_token, OAuthToken):
+            self._o_auth_token = OAuthToken.from_dictionary(
+                APIHelper.to_dictionary(auth_credentials_model.o_auth_token))
+        else:
+            self._o_auth_token = auth_credentials_model.o_auth_token \
+                if auth_credentials_model is not None else None
+        if auth_credentials_model is not None \
+                and isinstance(auth_credentials_model.o_auth_scopes, list):
+            self._o_auth_scopes = auth_credentials_model.o_auth_scopes
+        else:
+            self._o_auth_scopes = None
+        self._config = config
+        self._o_auth_api = OAuthAuthorizationController(config)
+        auth_params = {}
+        if (isinstance(self._o_auth_token, OAuthToken)
+                and hasattr(self._o_auth_token, "access_token")):
+            auth_params = {"Authorization": f"Bearer {self._o_auth_token.access_token}"}
+        super().__init__(auth_params=auth_params)
+
+    def is_valid(self):
+        """
+        Validate credentials for authentication.
+
+        Returns:
+            bool: True if the credentials are valid, False otherwise.
+
+        """
+        return (self._o_auth_token and isinstance(self._o_auth_token, OAuthToken)
+                and not self.is_token_expired(self._o_auth_token))
+
+    def get_authorization_url(self, state=None, additional_params=None):
+        """
+        Build and return an authorization URL. The user is expected to
+        obtain an authorization code from this URL and then call the authorize
+        function with that authorization code.
+
+        Args:
+            state (str): An opaque state string.
+            additional_params (dict): Any additional query parameters
+                to be added to the URL.
+
+        Returns:
+            str: The authorization URL.
+
+        """
+        auth_url = self._config.get_base_uri(Server.AUTH_SERVER)
+        auth_url += "/authorize"
+        query_params = {
+            "response_type": "code",
+            "client_id": self._o_auth_client_id,
+            "redirect_uri": self._o_auth_redirect_uri,
+        }
+        if self._o_auth_scopes:
+            query_params["scope"] = " ".join(self._o_auth_scopes)
+        if state:
+            query_params["state"] = state
+        if additional_params:
+            query_params.update(additional_params)
+        auth_url = APIHelper.append_url_with_query_parameters(auth_url, query_params)
+        return APIHelper.clean_url(auth_url)
+
+    def build_basic_auth_header(self):
+        """
+        Build the basic auth header for endpoints in the
+        OAuth Authorization Controller.
+
+        Returns:
+            str: The value of the Authentication header.
+
+        """
+        encoded = AuthHelper.get_base64_encoded_value(
+            self._o_auth_client_id,
+            self._o_auth_client_secret,
+        )
+        return f"Basic {encoded}"
+
+    def fetch_token(self, auth_code, additional_params=None):
+        """
+        Execute call to fetch the OAuth token.
+
+        Args:
+            auth_code (str): The authentication code.
+            additional_params (dict):  Any additional form parameters.
+
+        Returns:
+            OAuthToken: The OAuth token.
+
+        """
+        token = self._o_auth_api.request_token(
+            self.build_basic_auth_header(),
+            auth_code,
+            self._o_auth_redirect_uri,
+            _optional_form_parameters=additional_params,
+        ).body
+        if hasattr(token, "expires_in"):
+            current_utc_timestamp = AuthHelper.get_current_utc_timestamp()
+            token.expiry = AuthHelper.get_token_expiry(
+                current_utc_timestamp,
+                token.expires_in,
+            )
+        return token
+
+    def is_token_expired(self, o_auth_token=None):
+        """
+        Check if OAuth token has expired.
+
+        Args:
+            o_auth_token (OAuthToken): The OAuth token whose expiry is to be checked.
+
+        Returns:
+            bool: True if OAuth token has expired, False otherwise.
+
+        """
+        if o_auth_token is None:
+            return (hasattr(self._o_auth_token, "expiry")
+                    and AuthHelper.is_token_expired(
+                        self._o_auth_token.expiry))
+
+        return (hasattr(o_auth_token, "expiry")
+                and AuthHelper.is_token_expired(
+                    o_auth_token.expiry))
+
+    def refresh_token(self, additional_params=None):
+        """
+        Execute call to refresh the OAuth token.
+
+        Args:
+            additional_params (dict):  Any additional form parameters.
+
+        Returns:
+            OAuthToken: The refreshed OAuth token.
+
+        """
+        token = self._o_auth_api.refresh_token(
+            self.build_basic_auth_header(),
+            self._o_auth_token.refresh_token,
+            " ".join(self._o_auth_scopes) if self._o_auth_scopes else None,
+            _optional_form_parameters=additional_params,
+        ).body
+        if hasattr(token, "expires_in"):
+            current_utc_timestamp = AuthHelper.get_current_utc_timestamp()
+            token.expiry = AuthHelper.get_token_expiry(
+                current_utc_timestamp,
+                token.expires_in,
+            )
+        return token
+
+
+class AuthorizationCodeAuthCredentials:
+    """
+    A model for authentication credentials. Provides simple validation,
+    cloning support, and optional construction from environment variables.
+    Suitable as a pattern for other auth models.
+    """
+
+    @property
+    def o_auth_client_id(self):
+        """
+        OAuth 2 Client ID.
+        """
+        return self._o_auth_client_id
+
+    @property
+    def o_auth_client_secret(self):
+        """
+        OAuth 2 Client Secret.
+        """
+        return self._o_auth_client_secret
+
+    @property
+    def o_auth_redirect_uri(self):
+        """
+        OAuth 2 Redirection endpoint or Callback Uri.
+        """
+        return self._o_auth_redirect_uri
+
+    @property
+    def o_auth_token(self):
+        """
+        Object for storing information about the OAuth token.
+        """
+        return self._o_auth_token
+
+    @property
+    def o_auth_scopes(self):
+        """
+        List of scopes that apply to the OAuth token.
+        """
+        return self._o_auth_scopes
+
+    def __init__(self, o_auth_client_id, o_auth_client_secret,
+                 o_auth_redirect_uri, o_auth_token=None, o_auth_scopes=None):
+        """
+        Initialize the credentials.
+
+        Args:
+            o_auth_client_id: The o_auth_client_id property value to set.
+            o_auth_client_secret: The o_auth_client_secret property value to set.
+            o_auth_redirect_uri: The o_auth_redirect_uri property value to set.
+            o_auth_token: The o_auth_token property value to set.
+            o_auth_scopes: The o_auth_scopes property value to set.
+
+        Raises:
+            ValueError: If any required value is missing.
+
+        """
+        if o_auth_client_id is None:
+            raise ValueError("o_auth_client_id cannot be None")
+        if o_auth_client_secret is None:
+            raise ValueError("o_auth_client_secret cannot be None")
+        if o_auth_redirect_uri is None:
+            raise ValueError("o_auth_redirect_uri cannot be None")
+        self._o_auth_client_id = o_auth_client_id
+        self._o_auth_client_secret = o_auth_client_secret
+        self._o_auth_redirect_uri = o_auth_redirect_uri
+        self._o_auth_token = o_auth_token
+        self._o_auth_scopes = o_auth_scopes
+
+    def clone_with(self, o_auth_client_id=None, o_auth_client_secret=None,
+                   o_auth_redirect_uri=None, o_auth_token=None,
+                   o_auth_scopes=None):
+        """
+        Return a new instance with optional value overrides.
+
+        Args:
+            o_auth_client_id: The o_auth_client_id property value to set.
+            o_auth_client_secret: The o_auth_client_secret property value to set.
+            o_auth_redirect_uri: The o_auth_redirect_uri property value to set.
+            o_auth_token: The o_auth_token property value to set.
+            o_auth_scopes: The o_auth_scopes property value to set.
+
+        """
+        return AuthorizationCodeAuthCredentials(
+            o_auth_client_id or self.o_auth_client_id,
+            o_auth_client_secret or self.o_auth_client_secret,
+            o_auth_redirect_uri or self.o_auth_redirect_uri,
+            o_auth_token or self.o_auth_token,
+            o_auth_scopes or self.o_auth_scopes)
+
+    @classmethod
+    def from_environment(cls):
+        """
+        Create credentials from environment variables, if available.
+
+        Returns:
+            A credentials instance or ``None`` if values are missing.
+
+        """
+        o_auth_client_id = os.getenv(
+            "O_AUTH_CLIENT_ID",
+            None,
+        )
+        o_auth_client_secret = os.getenv(
+            "O_AUTH_CLIENT_SECRET",
+            None,
+        )
+        o_auth_redirect_uri = os.getenv(
+            "O_AUTH_REDIRECT_URI",
+            None,
+        )
+        o_auth_scopes = os.getenv(
+            "O_AUTH_SCOPES",
+            None,
+        )
+
+        if (o_auth_client_id is None
+                or o_auth_client_secret is None
+                or o_auth_redirect_uri is None):
+            return None
+
+        o_auth_scopes = [
+            v.strip() for v in o_auth_scopes.split(",") if v.strip()
+        ] if o_auth_scopes else None
+
+        return cls(
+            o_auth_client_id=o_auth_client_id,
+            o_auth_client_secret=o_auth_client_secret,
+            o_auth_redirect_uri=o_auth_redirect_uri,
+            o_auth_scopes=o_auth_scopes,
+        )

spotifywebapi/http/http_call_back.py

@@ -0,0 +1,20 @@
+
+"""
+spotifywebapi
+
+This file was automatically generated by APIMATIC v3.0 (
+ https://www.apimatic.io ).
+"""
+
+from apimatic_core.http.http_callback import HttpCallBack as CoreHttpCallback
+
+
+class HttpCallBack(CoreHttpCallback):
+    """
+    An interface for the callback to be called before and after the
+    HTTP call for an endpoint is made.
+
+    This class should not be instantiated but should be used as a base class
+    for HttpCallBack classes.
+
+    """

spotifywebapi/http/http_client_provider.py

@@ -0,0 +1,23 @@
+"""
+ spotifywebapi
+
+ This file was automatically generated by APIMATIC v3.0 ( https://www.apimatic.io ).
+"""
+from abc import ABC
+
+from apimatic_core_interfaces.client.http_client_provider import (
+    HttpClientProvider as CoreHttpClientProvider,
+)
+
+
+class HttpClientProvider(CoreHttpClientProvider, ABC):
+    """
+     Defines a contract for providing HTTP client configuration.
+
+     Classes implementing this interface are expected to supply a configured
+     HTTP session and timeout value that will be used by the SDK's internal
+     HTTP layer when making network requests.
+
+     This allows developers to inject their own custom HTTP clients while
+     maintaining compatibility with the SDK's request/response handling.
+    """

spotifywebapi/http/http_method_enum.py

@@ -0,0 +1,25 @@
+
+"""
+spotifywebapi
+
+This file was automatically generated by APIMATIC v3.0 (
+ https://www.apimatic.io ).
+"""
+
+from apimatic_core_interfaces.types.http_method_enum import (
+    HttpMethodEnum as CoreHttpMethodEnum,
+)
+
+
+class HttpMethodEnum(CoreHttpMethodEnum):
+    """
+    Enumeration of an HTTP Method
+
+    Attributes:
+        GET: A GET Request
+        POST: A POST Request
+        PUT: A PUT Request
+        PATCH: A PATCH Request
+        DELETE: A DELETE Request
+
+    """

spotifywebapi/http/http_request.py

@@ -0,0 +1,55 @@
+
+"""
+spotifywebapi
+
+This file was automatically generated by APIMATIC v3.0 (
+ https://www.apimatic.io ).
+"""
+
+from apimatic_core.http.request.http_request import HttpRequest as CoreHttpRequest
+
+
+class HttpRequest(CoreHttpRequest):
+    """
+    Represent an HTTP request to be sent to the server.
+
+    Encapsulates request details such as the HTTP method, target URL, headers,
+     query parameters, body parameters, and any files included with the request.
+
+    Attributes:
+        http_method: The HTTP method to use for the request.
+        query_url (str): The URL to which the request will be sent.
+        headers (dict[str, str] | None): Headers to include with the request.
+        query_parameters (dict[str, str] | None): Query parameters appended
+            to the request URL.
+        parameters (dict[str, str] | None): Form or body parameters sent
+            with the request.
+        files (dict | None): Files to be sent with the request.
+
+    """
+
+    def __init__(self,
+                 http_method,
+                 query_url,
+                 headers=None,
+                 query_parameters=None,
+                 parameters=None,
+                 files=None):
+        """
+        Initialize an HttpRequest instance.
+
+        Args:
+            http_method: The HTTP method to use for the request.
+            query_url: The URL to which the request will be sent.
+            headers: Headers to include with the request.
+            query_parameters: Query parameters appended to the request URL.
+            parameters: Form or body parameters sent with the request.
+            files: Files to be sent with the request.
+
+        """
+        super().__init__(http_method,
+                         query_url,
+                         headers,
+                         query_parameters,
+                         parameters,
+                         files)

spotifywebapi/http/http_response.py

@@ -0,0 +1,45 @@
+
+"""
+spotifywebapi
+
+This file was automatically generated by APIMATIC v3.0 (
+ https://www.apimatic.io ).
+"""
+
+from apimatic_core.http.response.http_response import HttpResponse as CoreHttpResponse
+
+
+class HttpResponse(CoreHttpResponse):
+    """
+    Represent an HTTP response returned by the server.
+
+    Stores response metadata such as status code, reason phrase, headers, and
+     the raw response body, along with the originating request.
+
+    Attributes:
+        status_code (int): The HTTP status code returned by the server.
+        reason_phrase (str): The reason phrase associated with the status code.
+        headers (dict[str, str]): Response headers as key-value pairs.
+        text (str): The raw response body as a string.
+        request: The request object that resulted in this response.
+
+    """
+
+    def __init__(self,
+                 status_code,
+                 reason_phrase,
+                 headers,
+                 text,
+                 request):
+        """
+        Initialize an HttpResponse instance.
+
+        Args:
+            status_code: The HTTP status code returned by the server.
+            reason_phrase: The reason phrase associated with the status code.
+            headers: Response headers as key-value pairs.
+            text: The raw response body as a string.
+            request: The request object that resulted in this response.
+
+        """
+        super().__init__(status_code, reason_phrase, headers, text, request)

spotifywebapi/http/proxy_settings.py

@@ -0,0 +1,50 @@
+"""
+spotifywebapi
+
+This file was automatically generated by APIMATIC v3.0 (
+ https://www.apimatic.io ).
+"""
+
+import os
+from typing import Optional
+
+from apimatic_core.http.configurations.proxy_settings import (
+    ProxySettings as CoreProxySettings,
+)
+
+
+class ProxySettings(CoreProxySettings):
+    """A simple data model for configuring HTTP(S) proxy settings."""
+
+    @classmethod
+    def from_environment(cls) -> Optional["ProxySettings"]:
+        """
+        Create an instance of this class using environment-based configuration.
+
+        This method attempts to construct and return an instance using relevant
+        environment variables, if available. If the required configuration is
+        not present, it may return `None` to indicate that no valid instance
+        could be created.
+
+        Returns:
+            Optional[cls]: A configured instance of this class, or `None` if
+            configuration data is missing or invalid.
+
+        """
+        address = os.getenv("PROXY_ADDRESS", None)
+        if not address:
+            return None
+
+        port = os.getenv("PROXY_PORT", None)
+        if port is not None:
+            try:
+                port = int(port)
+            except (TypeError, ValueError):
+                port = None
+
+        return cls(
+            address=address,
+            port=port,
+            username=os.getenv("PROXY_USERNAME", None),
+            password=os.getenv("PROXY_PASSWORD", None),
+        )

spotifywebapi/models/__init__.py

@@ -0,0 +1,142 @@
+# ruff: noqa: D104 | Missing docstring in public package
+# ruff: noqa: RUF022 | `__all__` is not sorted
+__all__ = [
+    "album_base",
+    "album_group_enum",
+    "album_object",
+    "album_restriction_object",
+    "album_type_enum",
+    "artist_discography_album_object",
+    "artist_object",
+    "audio_analysis_object",
+    "audio_features_object",
+    "audiobook_base",
+    "audiobook_object",
+    "author_object",
+    "categories",
+    "category_object",
+    "chapter_base",
+    "chapter_object",
+    "chapter_restriction_object",
+    "context_object",
+    "copyright_object",
+    "currently_playing_context_object",
+    "currently_playing_object",
+    "cursor_object",
+    "cursor_paged_artists",
+    "cursor_paging_object",
+    "cursor_paging_play_history_object",
+    "cursor_paging_simplified_artist_object",
+    "device_object",
+    "disallows_object",
+    "episode_base",
+    "episode_object",
+    "episode_restriction_object",
+    "error_object",
+    "explicit_content_settings_object",
+    "external_id_object",
+    "external_url_object",
+    "followers_object",
+    "image_object",
+    "include_external_enum",
+    "item_type_1_enum",
+    "item_type_2_enum",
+    "item_type_3_enum",
+    "item_type_enum",
+    "linked_track_object",
+    "many_albums",
+    "many_artists",
+    "many_audio_features",
+    "many_audiobooks",
+    "many_chapters",
+    "many_devices",
+    "many_episodes",
+    "many_genres",
+    "many_simplified_shows",
+    "many_tracks",
+    "markets",
+    "me_albums_request",
+    "me_episodes_request",
+    "me_episodes_request_1",
+    "me_following_request",
+    "me_following_request_1",
+    "me_player_play_request",
+    "me_player_request",
+    "me_shows_request",
+    "me_tracks_request",
+    "me_tracks_request_1",
+    "meta",
+    "mode_enum",
+    "narrator_object",
+    "o_auth_provider_error_enum",
+    "o_auth_scope_enum",
+    "o_auth_token",
+    "paged_albums",
+    "paged_categories",
+    "paging_artist_discography_album_object",
+    "paging_artist_object",
+    "paging_featured_playlist_object",
+    "paging_object",
+    "paging_playlist_object",
+    "paging_playlist_track_object",
+    "paging_saved_album_object",
+    "paging_saved_audiobook_object",
+    "paging_saved_episode_object",
+    "paging_saved_show_object",
+    "paging_saved_track_object",
+    "paging_simplified_album_object",
+    "paging_simplified_audiobook_object",
+    "paging_simplified_chapter_object",
+    "paging_simplified_episode_object",
+    "paging_simplified_show_object",
+    "paging_simplified_track_object",
+    "paging_track_object",
+    "play_history_object",
+    "playlist_object",
+    "playlist_owner_object",
+    "playlist_snapshot_id",
+    "playlist_track_object",
+    "playlist_tracks_ref_object",
+    "playlist_user_object",
+    "playlists_followers_request",
+    "playlists_request",
+    "playlists_tracks_request",
+    "playlists_tracks_request_1",
+    "playlists_tracks_request_2",
+    "private_user_object",
+    "public_user_object",
+    "queue_object",
+    "reason_enum",
+    "recommendation_seed_object",
+    "recommendations_object",
+    "release_date_precision_enum",
+    "resume_point_object",
+    "saved_album_object",
+    "saved_audiobook_object",
+    "saved_episode_object",
+    "saved_show_object",
+    "saved_track_object",
+    "search_items",
+    "section_object",
+    "segment_object",
+    "show_base",
+    "show_object",
+    "simplified_album_object",
+    "simplified_artist_object",
+    "simplified_playlist_object",
+    "simplified_track_object",
+    "time_interval_object",
+    "track",
+    "track_1",
+    "track_object",
+    "track_restriction_object",
+    "type_2_enum",
+    "type_3_enum",
+    "type_4_enum",
+    "type_5_enum",
+    "type_6_enum",
+    "type_8_enum",
+    "type_9_enum",
+    "type_enum",
+    "users_playlists_request",
+]