simfile.base
============

.. py:module:: simfile.base

.. autoapi-nested-parse::

   Base classes for simfile & chart implementations.

   This module should ideally never need to be used directly, but its
   documentation may be useful for understanding the similarities between
   the SM and SSC formats.



Classes
-------

.. autoapisummary::

   simfile.base.BaseChart
   simfile.base.BaseCharts
   simfile.base.BaseSimfile


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

.. py:class:: BaseChart

   Bases: :py:obj:`BaseObject`


   One chart from a simfile.

   All charts have the following known properties: `stepstype`,
   `description`, `difficulty`, `meter`, `radarvalues`, and `notes`.


   .. py:attribute:: stepstype


   .. py:attribute:: description


   .. py:attribute:: difficulty


   .. py:attribute:: meter


   .. py:attribute:: radarvalues


   .. py:attribute:: notes


   .. py:method:: blank()
      :classmethod:

      :abstractmethod:


      Generate a blank, valid chart populated with standard keys.

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



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

   Bases: :py:obj:`simfile._private.generic.ListWithRepr`\ [\ :py:obj:`AC`\ ], :py:obj:`simfile._private.msd_serializable.MSDSerializable`, :py:obj:`Generic`\ [\ :py:obj:`AC`\ , :py:obj:`C`\ , :py:obj:`S`\ ]


   List containing all of a simfile's charts.


   .. py:method:: serialize(file: TextIO)

      Write the object to provided text file object as MSD.



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

   Bases: :py:obj:`BaseObject`


   A simfile, including its metadata (e.g. song title) and charts.

   Metadata is stored directly on the simfile object through a
   dict-like interface. Keys are unique (if there are duplicates, the
   last value wins) and converted to uppercase.

   Additionally, properties recognized by the current stable version
   of StepMania are exposed through lower-case properties on the
   object for easy (and implicitly spell-checked) access. The
   following known properties are defined:

   * Metadata: `title`, `subtitle`, `artist`, `titletranslit`,
     `subtitletranslit`, `artisttranslit`, `genre`, `credit`,
     `samplestart`, `samplelength`, `selectable`, `instrumenttrack`,
     `timesignatures`
   * File paths: `banner`, `background`, `lyricspath`, `cdtitle`,
     `music`
   * Gameplay events: `bgchanges`, `fgchanges`, `keysounds`, `attacks`,
     `tickcounts`
   * Timing data: `offset`, `bpms`, `stops`, `delays`

   If a desired simfile property isn't in this list, it can still be
   accessed as a dict item.

   By default, the underlying parser will throw an exception if it
   finds any stray text between parameters. This behavior can be
   overridden by setting `strict` to False in the constructor.


   .. py:attribute:: MULTI_VALUE_PROPERTIES
      :value: ('ATTACKS', 'DISPLAYBPM', 'UNLOCKSTEPS')



   .. py:attribute:: title


   .. py:attribute:: subtitle


   .. py:attribute:: artist


   .. py:attribute:: titletranslit


   .. py:attribute:: subtitletranslit


   .. py:attribute:: artisttranslit


   .. py:attribute:: genre


   .. py:attribute:: credit


   .. py:attribute:: banner


   .. py:attribute:: background


   .. py:attribute:: lyricspath


   .. py:attribute:: cdtitle


   .. py:attribute:: music


   .. py:attribute:: offset


   .. py:attribute:: bpms


   .. py:attribute:: stops


   .. py:attribute:: delays


   .. py:attribute:: timesignatures


   .. py:attribute:: tickcounts


   .. py:attribute:: instrumenttrack


   .. py:attribute:: samplestart


   .. py:attribute:: samplelength


   .. py:attribute:: displaybpm


   .. py:attribute:: selectable


   .. py:attribute:: bgchanges


   .. py:attribute:: fgchanges


   .. py:attribute:: keysounds


   .. py:attribute:: attacks


   .. py:property:: charts
      :type: BaseCharts

      :abstractmethod:


      List of charts associated with this simfile.



   .. py:method:: blank()
      :classmethod:

      :abstractmethod:


      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:method:: serialize(file: TextIO)

      Write the object to provided text file object as MSD.