simfile.convert
===============

.. py:module:: simfile.convert

.. autoapi-nested-parse::

   Functions for converting SM to SSC simfiles and vice-versa.



Exceptions
----------

.. autoapisummary::

   simfile.convert.InvalidPropertyException


Classes
-------

.. autoapisummary::

   simfile.convert.PropertyType
   simfile.convert.InvalidPropertyBehavior


Functions
---------

.. autoapisummary::

   simfile.convert.sm_to_ssc
   simfile.convert.ssc_to_sm


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

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

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


   Types of known properties.

   These roughly mirror the lists of known properties documented in
   :class:`.BaseSimfile` and :class:`.SSCSimfile`.


   .. py:attribute:: SSC_VERSION
      :value: 1


      The SSC version tag.



   .. py:attribute:: METADATA
      :value: 2


      Properties that don't affect the gameplay.



   .. py:attribute:: FILE_PATH
      :value: 3


      Properties that reference file paths (e.g. images).



   .. py:attribute:: GAMEPLAY_EVENT
      :value: 4


      Properties that affect gameplay in some fashion.



   .. py:attribute:: TIMING_DATA
      :value: 5


      Properties that influence when notes must be hit.



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

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


   How to handle an invalid property during conversion.


   .. py:attribute:: COPY_ANYWAY
      :value: 1


      Copy the property regardless of the destination type.



   .. py:attribute:: IGNORE
      :value: 2


      Do not copy the property.



   .. py:attribute:: ERROR_UNLESS_DEFAULT
      :value: 3


      Raise :class:`InvalidPropertyException` unless the property's value is
      the default for its field.

      The "default value" for most properties is an empty string. If the
      destination type's :code:`.blank` output has a non-empty value for the
      property, that value is considered the default instead.



   .. py:attribute:: ERROR
      :value: 4


      Raise :class:`InvalidPropertyException` regardless of the value.



.. py:exception:: InvalidPropertyException

   Bases: :py:obj:`Exception`


   Raised by conversion functions if a property cannot be converted.


.. py:function:: sm_to_ssc(sm_simfile: simfile.sm.SMSimfile, *, simfile_template: Optional[simfile.ssc.SSCSimfile] = None, chart_template: Optional[simfile.ssc.SSCChart] = None) -> simfile.ssc.SSCSimfile

   Convert an SM simfile to an equivalent SSC simfile.

   `simfile_template` and `chart_template` can optionally be provided
   to define the initial simfile and chart prior to copying properties
   from the source object. If they are not provided,
   :meth:`.SSCSimfile.blank` and :meth:`.SSCChart.blank` will supply the
   template objects.


.. py:function:: ssc_to_sm(ssc_simfile: simfile.ssc.SSCSimfile, *, simfile_template: Optional[simfile.sm.SMSimfile] = None, chart_template: Optional[simfile.sm.SMChart] = None, invalid_property_behaviors: InvalidPropertyBehaviorMapping = {}) -> simfile.sm.SMSimfile

   Convert an SSC simfile to an equivalent SM simfile.

   `simfile_template` and `chart_template` can optionally be provided
   to define the initial simfile and chart prior to copying properties
   from the source object. If they are not provided,
   :meth:`.SMSimfile.blank` and :meth:`.SMChart.blank` will supply
   the template objects.

   Not all SSC properties are valid for SM simfiles, including some
   gameplay events and timing data. If one of those types of properties
   are found and contain a non-default value,
   :class:`InvalidPropertyException` will be raised.

   The behavior described above can be changed by supplying the
   `invalid_property_behaviors` parameter, which maps
   :class:`PropertyType` to :class:`InvalidPropertyBehavior` values.
   This mapping need not cover every :class:`PropertyType`; any missing
   values will fall back to the default mapping described
   above.