Skip to content

sok.file_operations.game_operations

File operations for video games.

This module handles:

  • Detection and extraction of information from game file names
  • Automatic renaming
  • Organization by platform/console
  • Version detection (region, revision, etc.)

GameFileOperations

class GameFileOperations

Bases: FileOperations, FileParsingMixin, FileValidationMixin, FileListOrganizerMixin

File operations for video game files.

Provides methods to extract metadata from game filenames, detect versions (region, revision), organize by platform, and rename according to ROM/ISO conventions.

Source

Attributes

Name
PLATFORMS
REGIONS

supported_extensionsproperty

List[str]

Return list of supported game file extensions.

batch_target

def batch_target(
media_item: MediaItem,
file_path: Path,
alone: bool,
) -> Tuple[List[str], str]:

Folders and file name of one game file of a batch.

A game of one file goes to Platform/, renamed. A game of several files (a .cue and its .bin, several discs) goes to Platform/Title (Year)/ and keeps its file names: a .cue names its .bin files, so renaming them would break it.

Parameters

NameTypeDescription
media_itemMediaItemThe Game of the file.
file_pathPathThe file.
aloneboolFalse when the game has other files in the batch.

Returns

  • Tuple[List[str], str]The folders under the destination, and the new file name.
Source

detect_platform

def detect_platform(file_path: Path) -> Optional[str]:

Platform of a game file: from a "[SNES]" tag, its extension or its folders ("PS1/", "GameCube/"…).

Parameters

NameTypeDescription
file_pathPathThe game file.

Returns

  • Optional[str]The platform name, or None if nothing tells it.
Source

detect_platform_from_extension

def detect_platform_from_extension(extension: str) -> Optional[str]:

Detects the platform from the file extension

Parameters

NameTypeDescription
extensionstr
Source

extract_info_from_filename

def extract_info_from_filename(filename: str) -> Dict[str, Any]:

Extract information from a game filename.

The input patterns of the settings are tried first (sok.core.name_patterns); the name is otherwise read by the rules of _parse_filename. "pattern" is the pattern that matched, if any.

Parameters

NameTypeDescription
filenamestrFile name to parse.

Returns

  • Dict[str, Any]Dictionary with extracted information.
Source

find_files

def find_files(directory: str, recursive: bool = True) -> List[str]:

Unified alias for find_game_files.

Parameters

NameTypeDefaultDescription
directorystr
recursiveboolTrue
Source

find_game_files

def find_game_files(directory: str, recursive: bool = True) -> List[str]:

Find all game files in a directory.

Parameters

NameTypeDefaultDescription
directorystrDirectory to scan.
recursiveboolTrueEnable recursive search.

Returns

  • List[str]List of game file paths.
Source

generate_new_filename

def generate_new_filename(
media_item: Optional[MediaItem],
original_filename: str,
) -> str:

Generate a new filename for a game.

With a game found online, the game format of the settings. By default its title followed by the tags of the original name, which ROM collections rely on: 'Super Mario World (USA) (Rev 1).sfc'. Otherwise 'Game Title (Region) [Code].ext' from the original name.

Parameters

NameTypeDescription
media_itemOptional[MediaItem]The media item (Game), or None.
original_filenamestrOriginal filename.

Returns

  • strNew filename.
Source

organize_by_platform

def organize_by_platform(
source_path: str,
dest_path: str,
use_folder_structure: bool = True,
dry_run: bool = False,
) -> Dict[str, Any]:

Organize game files by platform.

Created structure: Platform/Game.rom

Parameters

NameTypeDefaultDescription
source_pathstrSource folder.
dest_pathstrDestination folder.
use_folder_structureboolTrueUse folder structure to detect platform.
dry_runboolFalseSimulation mode.

Returns

  • Dict[str, Any]Organization report.
Source

Attributes

NameValue
loggerlogging.getLogger(__name__)
Built with Kiln