simfile

Convenience functions for loading & modifying simfiles.

All functions take a strict parameter that defaults to False (except mutate(), which defaults to True). When strict is set to True, the underlying parser will throw an exception if it finds any stray text between parameters.

Submodules

• simfile.assets
• simfile.base
• simfile.convert
• simfile.dir
• simfile.notes
• simfile.sm
• simfile.ssc
• simfile.tidy
• simfile.timing
• simfile.types

Exceptions

CancelMutation

Raise this exception from inside a mutate() block

Functions

load(→ types.Simfile)	Load a text file object as a simfile.
loads(→ types.Simfile)	Load a string containing simfile data as a simfile.
open(, **kwargs) → types.Simfile)	Load a simfile by filename.
open_with_detected_encoding(, ...)	Load a simfile by filename; returns the simfile and detected encoding.
opendir(, **kwargs) → tuple[types.Simfile, str])	Open a simfile from its directory path;
openpack(, ...)	Open a pack of simfiles from the pack's directory path;
mutate(, ...)	Context manager that loads a simfile by filename,

Package Contents

simfile.load(file: TextIO, strict: bool = False, errors: str | None = None) → types.Simfile

Load a text file object as a simfile.

If the file object has a filename with a matching extension, it will be used to infer the correct implementation. Otherwise, the first property in the file is peeked at. If its key is “VERSION”, the file is treated as an SSC simfile; otherwise, it’s treated as an SM simfile.

simfile.loads(string: str, strict: bool = False) → types.Simfile

Load a string containing simfile data as a simfile.

simfile.open(filename: str, strict: bool = False, filesystem: _private.fs.FS = NativeOSFS(), **kwargs) → types.Simfile

Load a simfile by filename.

Keyword arguments are passed to the builtin open function. If no encoding is specified, this function will defer to open_with_detected_encoding().

simfile.open_with_detected_encoding(filename: str, try_encodings: list[str] = ENCODINGS, strict: bool = False, filesystem: _private.fs.FS = NativeOSFS(), **kwargs) → tuple[types.Simfile, str]

Load a simfile by filename; returns the simfile and detected encoding.

Tries decoding the simfile as UTF-8, CP1252 (English), CP932 (Japanese), and CP949 (Korean), mirroring the encodings supported by StepMania. This list can be overridden by supplying try_encodings. If all encodings fail in non-strict parsing, the simfile will instead be loaded using ASCII with surrogate escapes, which should never fail.

Keep in mind that no heuristics are performed to “guess” the correct encoding - this function simply tries each encoding in order until one succeeds. As such, non-UTF-8 files may successfully parse as the wrong encoding, resulting in mojibake. If you intend to write the simfile back to disk, make sure to use the same encoding that was detected to preserve the true byte sequence.

In general, you only need to use this function directly if you need to know the file’s encoding. open() and mutate() both defer to this function to detect the encoding behind the scenes.

simfile.opendir(simfile_dir: str, filesystem: _private.fs.FS = NativeOSFS(), **kwargs) → tuple[types.Simfile, str]

Open a simfile from its directory path; returns a (simfile, filename) tuple.

If both SSC and SM are present, SSC is preferred. Keyword arguments are passed down to simfile.open().

If you need more flexibility (for example, if you need both the SM and SSC files), try using SimfileDirectory.

simfile.openpack(pack_dir: str, filesystem: _private.fs.FS = NativeOSFS(), **kwargs) → collections.abc.Iterator[tuple[types.Simfile, str]]

Open a pack of simfiles from the pack’s directory path; yields (simfile, filename) tuples.

Only immediate subdirectories of pack_dir containing an SM or SSC file are included. Simfiles aren’t guaranteed to appear in any particular order. If both SSC and SM are present, SSC is preferred. Keyword arguments are passed down to simfile.open().

If you need more flexibility (for example, if you need the pack’s banner, or both the SM and SSC files), try using SimfilePack.

exception simfile.CancelMutation

Bases: BaseException

Raise this exception from inside a mutate() block to prevent saving the simfile.

simfile.mutate(input_filename: str, output_filename: str | None = None, backup_filename: str | None = None, try_encodings: list[str] = ENCODINGS, strict: bool = True, filesystem: _private.fs.FS = NativeOSFS(), **kwargs) → collections.abc.Iterator[types.Simfile]

Context manager that loads a simfile by filename, runs its with block, then saves the simfile back to disk.

If an output_filename is provided, the modified simfile will be written to that filename upon exit from the context manager. If no output_filename is provided, the modified simfile will be written back to the input_filename instead.

If a backup_filename is provided, the original simfile will additionally be written to that filename upon exit from the context manager. Otherwise, no backup copy will be written. backup_filename must be distinct from input_filename and output_filename if present.

If the context manager catches an exception, nothing will be written to disk, and the exception will be re-thrown. To prevent saving without causing the context manager to re-throw an exception, raise CancelMutation.

This function uses open_with_detected_encoding() under the hood to detect & preserve the input file’s encoding. The list of encodings can be overridden by supplying try_encodings.

Any extra kwargs are passed to the builtin open function.