simfile.convert

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

Exceptions

InvalidPropertyException

Raised by conversion functions if a property cannot be converted.

Classes

PropertyType	Types of known properties.
InvalidPropertyBehavior	How to handle an invalid property during conversion.

Functions

sm_to_ssc(→ simfile.ssc.SSCSimfile)	Convert an SM simfile to an equivalent SSC simfile.
ssc_to_sm(→ simfile.sm.SMSimfile)	Convert an SSC simfile to an equivalent SM simfile.

Module Contents

class simfile.convert.PropertyType(*args, **kwds)

Bases: enum.Enum

Types of known properties.

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

SSC_VERSION = 1

The SSC version tag.

METADATA = 2

Properties that don’t affect the gameplay.

FILE_PATH = 3

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

GAMEPLAY_EVENT = 4

Properties that affect gameplay in some fashion.

TIMING_DATA = 5

Properties that influence when notes must be hit.

class simfile.convert.InvalidPropertyBehavior(*args, **kwds)

Bases: enum.Enum

How to handle an invalid property during conversion.

COPY_ANYWAY = 1

Copy the property regardless of the destination type.

IGNORE = 2

Do not copy the property.

ERROR_UNLESS_DEFAULT = 3

Raise 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 .blank output has a non-empty value for the property, that value is considered the default instead.

ERROR = 4

Raise InvalidPropertyException regardless of the value.

exception simfile.convert.InvalidPropertyException

Bases: Exception

Raised by conversion functions if a property cannot be converted.

simfile.convert.sm_to_ssc(sm_simfile: simfile.sm.SMSimfile, *, simfile_template: simfile.ssc.SSCSimfile | None = None, chart_template: simfile.ssc.SSCChart | None = 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, SSCSimfile.blank() and SSCChart.blank() will supply the template objects.

simfile.convert.ssc_to_sm(ssc_simfile: simfile.ssc.SSCSimfile, *, simfile_template: simfile.sm.SMSimfile | None = None, chart_template: simfile.sm.SMChart | None = 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, SMSimfile.blank() and 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, InvalidPropertyException will be raised.

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