simfile

Convenience functions for loading & modifying simfiles.

All functions take a strict parameter that defaults to True. 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.

Subpackages

• simfile.notes
  • simfile.notes.count
  • simfile.notes.group
  • simfile.notes.timed
• simfile.timing
  • simfile.timing.displaybpm
  • simfile.timing.engine

Submodules

• simfile.assets
• simfile.base
• simfile.convert
• simfile.dir
• simfile.sm
• simfile.ssc
• simfile.types

Package Contents

Functions

load(file: Union[TextIO, Iterator[str]], strict: bool = True) → types.Simfile	Load a text file object as a simfile.
loads(string: str, strict: bool = True) → types.Simfile	Load a string containing simfile data as a simfile.
open(filename: str, strict: bool = True, filesystem: fs.base.FS = NativeOSFS(), **kwargs) → types.Simfile	Load a simfile by filename.
open_with_detected_encoding(filename: str, try_encodings: List[str] = ENCODINGS, strict: bool = True, filesystem: fs.base.FS = NativeOSFS(), **kwargs) → Tuple[types.Simfile, str]	Load a simfile by filename; returns the simfile and detected encoding.
opendir(simfile_dir: str, filesystem: fs.base.FS = NativeOSFS(), **kwargs) → Tuple[types.Simfile, str]	Open a simfile from its directory path;
openpack(pack_dir: str, filesystem: fs.base.FS = NativeOSFS(), **kwargs) → Iterator[Tuple[types.Simfile, str]]	Open a pack of simfiles from the pack’s directory path;
mutate(input_filename: str, output_filename: Optional[str] = None, backup_filename: Optional[str] = None, try_encodings: List[str] = ENCODINGS, strict: bool = True, filesystem: fs.base.FS = NativeOSFS(), **kwargs) → Iterator[types.Simfile]	Context manager that loads & saves a simfile by filename.

simfile.load(file: Union[TextIO, Iterator[str]], strict: bool = True) → 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 = True) → types.Simfile

Load a string containing simfile data as a simfile.

simfile.open(filename: str, strict: bool = True, filesystem: fs.base.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 = True, filesystem: fs.base.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.

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: fs.base.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: fs.base.FS = NativeOSFS(), **kwargs) → 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 from inside a mutate() block to prevent saving the simfile.

simfile.mutate(input_filename: str, output_filename: Optional[str] = None, backup_filename: Optional[str] = None, try_encodings: List[str] = ENCODINGS, strict: bool = True, filesystem: fs.base.FS = NativeOSFS(), **kwargs) → Iterator[types.Simfile]

Context manager that loads & saves a simfile by filename.

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

If a backup_filename is provided, the original simfile will 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.

Keyword arguments are passed to the builtin open function. Uses open_with_detected_encoding() to detect & preserve the encoding. The list of encodings can be overridden by supplying try_encodings.