simfile.sm
==========

.. py:module:: simfile.sm

.. autoapi-nested-parse::

   Simfile & chart classes for SM files.



Attributes
----------

.. autoapisummary::

   simfile.sm.SM_CHART_PROPERTIES
   simfile.sm.SM_SIMFILE_PROPERTIES


Classes
-------

.. autoapisummary::

   simfile.sm.SMChart
   simfile.sm.AttachedSMChart
   simfile.sm.SMCharts
   simfile.sm.SMSimfile


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

.. py:data:: SM_CHART_PROPERTIES
   :value: ('STEPSTYPE', 'DESCRIPTION', 'DIFFICULTY', 'METER', 'RADARVALUES', 'NOTES')


   Pseudo-properties of .SM files, named how they are recognized internally.

   This sequence is sorted in the same order dictated by the .SM format.


.. py:class:: SMChart

   Bases: :py:obj:`simfile.base.BaseChart`


   SM implementation of :class:`~simfile.base.BaseChart`.

   Unlike :class:`~simfile.ssc.SSCChart`, SM chart metadata is stored
   as a fixed list of 6 properties, so this class prohibits adding or
   deleting keys from its backing OrderedDict.


   .. py:attribute:: extradata
      :type:  Optional[List[str]]
      :value: None


      If the chart data contains more than 6 components, the extra
      components will be stored in this attribute.



   .. py:method:: blank() -> SMChart
      :classmethod:


      Generate a blank, valid chart populated with standard keys.

      This should approximately match blank charts produced by the
      StepMania editor.



   .. py:method:: from_str(string: str) -> SMChart
      :classmethod:


      Parse the serialized MSD value components of a NOTES property.

      The string should contain six colon-separated components,
      corresponding to each of the base known properties documented in
      :class:`.BaseChart`. Any additional components will be stored in
      :data:`extradata`.

      Raises :code:`ValueError` if the string contains fewer than six
      components.

      .. deprecated:: 2.1
          This is now a less efficient version of :func:`from_msd`, which
          interoperates better with ``msdparser`` version 2.0.



   .. py:method:: from_msd(values: Sequence[str]) -> SMChart
      :classmethod:


      Parse the MSD value components of a NOTES property.

      The list should contain six strings, corresponding to each of the
      base known properties documented in :class:`.BaseChart`. Any
      additional components will be stored in :data:`extradata`.

      Raises :code:`ValueError` if the list contains fewer than six
      components.

      .. deprecated:: 3.0
          Use :func:`from_msd_parameter` instead. This method doesn't
          preserve whitespace or comments.



   .. py:method:: from_msd_parameter(param: msdparser.MSDParameter) -> SMChart
      :classmethod:


      Parse a NOTES parameter from an SM file.

      The parameter should contain seven components, corresponding to
      the "NOTES" key followed by the six base known properties
      documented in :class:`.BaseChart`. Any additional components
      will be stored in :data:`extradata`.

      Raises :code:`ValueError` if the parameter contains <7 components.



   .. py:method:: serialize(file)

      Write the object to provided text file object as MSD.



   .. py:method:: update(*args, **kwargs) -> None
      :abstractmethod:


      Raises NotImplementedError.



   .. py:method:: pop(property, default=None)
      :abstractmethod:


      Raises NotImplementedError.



   .. py:method:: popitem(last=True)
      :abstractmethod:


      Raises NotImplementedError.



   .. py:method:: values() -> frozenset[str]
      :abstractmethod:


      Raises NotImplementedError.



.. py:class:: AttachedSMChart

   Bases: :py:obj:`SMChart`, :py:obj:`simfile.base.BaseAttachedChart`


   SM implementation of :class:`~simfile.base.BaseChart`.

   Unlike :class:`~simfile.ssc.SSCChart`, SM chart metadata is stored
   as a fixed list of 6 properties, so this class prohibits adding or
   deleting keys from its backing OrderedDict.


   .. py:method:: detach() -> SMChart


.. py:class:: SMCharts(simfile: S, charts: Optional[Iterable[C]] = None)

   Bases: :py:obj:`simfile.base.BaseCharts`\ [\ :py:obj:`AttachedSMChart`\ , :py:obj:`SMChart`\ , :py:obj:`SMSimfile`\ ]


   SM implementation of :class:`~simfile.base.BaseCharts`.

   List elements are :class:`SMChart` instances.


   .. py:method:: append(chart: SMChart)

      Append object to the end of the list.



   .. py:method:: extend(iterable: Iterable[SMChart]) -> None

      Extend list by appending elements from the iterable.



.. py:data:: SM_SIMFILE_PROPERTIES
   :value: ('TITLE', 'SUBTITLE', 'ARTIST', 'TITLETRANSLIT', 'SUBTITLETRANSLIT', 'ARTISTTRANSLIT', 'GENRE',...


   All simfile-level properties of .SM files recognized by StepMania 5,
   including aliases.

   This sequence is sorted in the same order produced by the StepMania 5 editor.


.. py:class:: SMSimfile(*, file: Optional[TextIO] = None, string: Optional[str] = None, tokens: Optional[Iterable[Tuple[msdparser.lexer.MSDToken, str]]] = None, strict: bool = True)

   Bases: :py:obj:`simfile.base.BaseSimfile`


   SM implementation of :class:`~simfile.base.BaseSimfile`.


   .. py:attribute:: stops

      Specialized property for `STOPS` that supports `FREEZES` as an alias.



   .. py:method:: blank() -> SMSimfile
      :classmethod:


      Generate a blank, valid simfile populated with standard keys.

      This should approximately match the simfile produced by the
      StepMania editor in a directory with no .sm or .ssc files.



   .. py:property:: charts
      :type: SMCharts


      List of charts associated with this simfile.