:py:mod:`calliope.playlist`
===========================

.. py:module:: calliope.playlist


Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   calliope.playlist.PlaylistFormat
   calliope.playlist.PlaylistItem
   calliope.playlist.Playlist



Functions
~~~~~~~~~

.. autoapisummary::

   calliope.playlist.read
   calliope.playlist.write
   calliope.playlist.split
   calliope.playlist.load_schema



Attributes
~~~~~~~~~~

.. autoapisummary::

   calliope.playlist.Item


.. py:exception:: PlaylistError


   Bases: :py:obj:`RuntimeError`

   Unspecified run-time error.

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


.. py:exception:: UnhashableItem


   Bases: :py:obj:`PlaylistError`

   Unspecified run-time error.

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


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


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

   Playlist serialization formats.

     * ``XSPF``: `XML Shareable Playlist Format <https://www.xspf.org>`_
     * ``JSPF``: JSON variant of XSPF. Note that YAML is accepted as well.
     * ``CUE``: The `Cue sheet format <https://en.wikipedia.org/wiki/Cue_sheet_(computing)>`_
     * ``M3U``: M3U and Extended M3U. See `<https://en.wikipedia.org/wiki/M3U>`_
     * ``PLS``: The INI-based `PLS format <https://en.wikipedia.org/wiki/PLS_(file_format)>`_

   Check the :mod:`Import` and :mod:`Export` modules to see which formats
   they support.


   .. py:attribute:: CUE
      :value: 1

      

   .. py:attribute:: JSPF
      :value: 2

      

   .. py:attribute:: M3U
      :value: 3

      

   .. py:attribute:: PLS
      :value: 1

      

   .. py:attribute:: XSPF
      :value: 4

      


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


   Bases: :py:obj:`dict`

   Represents a single item in a Calliope playlist.

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

   .. py:method:: id()


   .. py:method:: __hash__()

      Return hash(self).


   .. py:method:: __str__()

      Return str(self).


   .. py:method:: add_warning(namespace, message)



.. py:data:: Item

   

.. py:class:: Playlist


   Bases: :py:obj:`list`

   Built-in mutable sequence.

   If no argument is given, the constructor creates a new empty list.
   The argument must be an iterable if specified.

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


.. py:function:: read(stream)

   Parses a playlist from the given stream.

   Returns an generator that produces calliope.playlist.Item objects.

   The generator will read from the file on demand, so you must be careful not
   to do this:

       with open('playlist.cpe', 'r') as f:
           playlist = calliope.playlist.read(f)

       for item in playlist:
           # You will see 'ValueError: I/O operation on closed file.'.
           ...

   If you want to read the playlist in one operation, convert it to a list:

       with open('playlist.cpe', 'r') as f:
           playlist = list(calliope.playlist.read(f))



.. py:function:: write(items, stream)

   Write a playlist to the given stream.


.. py:function:: split(items)

   Convert a list of items into a list of playlists.

   Splitting is done based on the `playlist.title` attribute. Each time an
   item is found with this attribute set, it's treated as a new playlist.



.. py:function:: load_schema()

   Returns the JSON Schema for Calliope playlist items.