:py:mod:`calliope.spotify`
==========================

.. py:module:: calliope.spotify

.. autoapi-nested-parse::

   Access data from the `Spotify music streaming service <https://www.spotify.com>`_.

   This module wraps the `Spotipy <https://spotipy.readthedocs.io/>`_ library.

   Authentication
   --------------

   You will need a :ref:`Spotify API key <api-keys.spotify>` to authenticate with
   Spotify.  The credentials should be provided when creating the
   :class:`calliope.spotify.SpotifyContext`.

   The first time :func:`calliope.spotify.SpotifyContext.authenticate` is called,
   it will open a browser window to authorize with Spotify, and will return the
   access token via a `local HTTP server <https://github.com/plamere/spotipy/pull/243/>`_
   or by asking to paste the redirected URI::

       $ cpe spotify export
       Couldn't read cache at: /home/sam/.cache/calliope/spotify/credentials.json
       Enter the URL you were redirected to:

   The authorization code will be saved in the cache so future API access will
   work without a prompt, until the cached code expires.

   Caching
   -------

   By default, all new HTTP requests are saved to disk. Cache expiry is done
   following ``etags`` and ``cache-control`` headers provided by the Spotify API.



Submodules
----------
.. toctree::
   :titlesonly:
   :maxdepth: 1

   schema/index.rst


Package Contents
----------------

Classes
~~~~~~~

.. autoapisummary::

   calliope.spotify.ContentResolver
   calliope.spotify.FeatMode
   calliope.spotify.SpotifyArtistInfo
   calliope.spotify.SpotifyContext



Functions
~~~~~~~~~

.. autoapisummary::

   calliope.spotify.select_best
   calliope.spotify.drop_none_values
   calliope.spotify.get_isrcs
   calliope.spotify.get_nested
   calliope.spotify.normalize_creator_title
   calliope.spotify.parse_sort_date
   calliope.spotify.resolve
   calliope.spotify.export
   calliope.spotify.export_library_tracks
   calliope.spotify.export_library_albums
   calliope.spotify.export_library_artists
   calliope.spotify.import_library
   calliope.spotify.import_
   calliope.spotify.top_artists



Attributes
~~~~~~~~~~

.. autoapisummary::

   calliope.spotify.Item


.. py:class:: ContentResolver


   Interface for modules that can resolve playable tracks.

   .. py:method:: authenticate()
      :abstractmethod:


   .. py:method:: resolve_content(playlist)
      :abstractmethod:



.. py:data:: Item

   

.. py:function:: select_best(item, candidates)

   Automatically select the best match Item from a list of candidates for a given item.

   For each candidate, a number of weighted priorities is computed, which
   comprise its overall priority. The item with the best priority is automatically
   selected if it is higher than 90%.

   :param item: A calliope playlist item to match
   :param candidates: A list of candidates

   :returns: The best match Item or None if no good match was found.


.. py:class:: FeatMode(*args, **kwds)


   Bases: :py:obj:`enum.Enum`

   Action to take for tracks which have "featured artists" listed.

   .. py:attribute:: KEEP

      

   .. py:attribute:: DROP

      

   .. py:attribute:: TO_CREATOR

      

   .. py:attribute:: TO_TITLE

      


.. py:function:: drop_none_values(dct)

   Delete all fields with None value from dct.


.. py:function:: get_isrcs(el)

   Find the ISRCs of item and return them as list


.. py:function:: get_nested(sequence, keys)

   Get the value from a nested dict/list data structure, returning None if one
   of the keys is invalid.


.. py:function:: normalize_creator_title(creator, title, feat_mode=FeatMode.TO_CREATOR)

   Remove featuring artists from title and append them to the artist string


.. py:function:: parse_sort_date(date_str)

   Parse a potentially incomplete date string of the format YYYY-MM-DD and
   return a datetime.date object with conservative defaults for missing data.


.. py:class:: SpotifyArtistInfo(data=None)


   Bases: :py:obj:`calliope.playlist.Item`

   Represents a single item in a Calliope playlist.

   Initialize self.  See help(type(self)) for accurate signature.


.. py:class:: SpotifyContext(client_id, client_secret, redirect_uri, caching = True)


   Bases: :py:obj:`calliope.interface.ContentResolver`

   Interface for modules that can resolve playable tracks.

   Context for accessing Spotify Web API.

   The :meth:`authenticate` function must be called to obtain a
   :class:`spotipy.client.Spotify` object.

   This class implements the :class:`calliope.interface.ContentResolver`
   interface.

   :param client_id: API client ID
   :param client_secret: API key
   :param redirect_uri: Redirect URI for web-based authentication flow
   :param caching: Enables caching to ``$XDG_CACHE_HOME/calliope/spotify``

   .. py:method:: authenticate()

      Authenticate against the Spotify API.

      See above for details on how this works.



   .. py:method:: resolve_content(*args, **kwargs)



.. py:function:: resolve(api, playlist, select_func=None, update=False)


.. py:function:: export(spotify, user_id = None)

   Export all playlists for given user.

   :param user_id: Optional, defaults to authenticated user.


.. py:function:: export_library_tracks(spotify)

   Export all library tracks for the current user


.. py:function:: export_library_albums(spotify)

   Export all library albums for the current user


.. py:function:: export_library_artists(spotify)

   Export all library artists for the current user


.. py:function:: import_library(context, playlist)

   Import items into the current user's spotify library. Supported types are
   tracks, albums and artists.


.. py:function:: import_(context, playlist, user_id = None)

   Import a playlist to Spotify.

   :param user_id: Optional, defaults to authenticated user. Requires
                   appropriate permissions.


.. py:function:: top_artists(spotify, count, time_range)

   Return top artists for the authenticated user.