niemafs package

NiemaFS is a Python library for reading data from various file system standards.

Module contents

class niemafs.DirFS(path, file_obj=None)

Bases: FileSystem

Class to represent a directory on disk

class niemafs.FileSystem(path=None, file_obj=None)

Bases: ABC

Base class to represent a file system

read_file(offset, length=None, return_to_init=False)

Read data from the underlying file-like object.

Args:

offset (int): The offset from which to start reading.

length (int): The number of bytes to read, or None to read to the end.

return_to_init (bool): True to seek back to the initial offset after finishing the read, otherwise False (faster)

Returns:

bytes: The read data.

class niemafs.GcRarcFS(file_obj, path=None)

Bases: FileSystem

Class to represent a Nintendo GameCube RARC (.arc) archives.

get_data_header()

Return the Data Header of the RARC.

Returns:

bytes: The Data Header of the RARC.

get_header()

Return the Header of the RARC.

Returns:

bytes: The Header of the RARC.

parse_data_header()

Return a parsed version of the Data Header of the RARC.

Returns:

dict: A parsed version of the Data Header of the RARC.

parse_dir_node()

Return a parsed version of a Directory Node of the RARC.

Args:

data (bytes): The raw Directory Node data

Returns:

dict: A parsed version of the Directory Node

parse_file_node()

Return a parsed version of a File Node of the RARC.

Args:

data (bytes): The raw File Node data

Returns:

dict: A parsed version of the File Node

parse_header()

Return a parsed version of the Header of the RARC.

Returns:

dict: A parsed version of the Header of the RARC.

parse_node_attributes()

Return a parsed version of the Attributes of a File Node of the RARC.

Args:

x (int): The integer representation of the Attributes of a File Node.

Returns:

dict: A parsed version of the Attributes.

class niemafs.GcmFS(file_obj, path=None)

Bases: FileSystem

Class to represent a Nintendo GameCube GCM mini-DVD.

get_appldr_bin()

Return the Apploader (“appldr.bin”) of the GCM.

Returns:

bytes: The Apploader (“appldr.bin”) of the GCM.

get_bi2_bin()

Return the Disc Header Information (“bi2.bin”) of the GCM.

Returns:

bytes: The Disc Header Information (“bi2.bin”) of the GCM.

get_boot_bin()

Return the Disk Header (“boot.bin”) of the GCM.

Returns:

bytes: The Disk Header (“boot.bin”) of the GCM.

get_fst_bin()

Return the File System Table (FST, “fst.bin”) of the GCM.

Returns:

bytes: The File System Table (FST, “fst.bin”) of the GCM.

parse_appldr_bin()

Return a parsed version of the Apploader (“appldr.bin”) of the GCM.

Returns:

dict: A parsed version of the Apploader (“appldr.bin”) of the GCM.

parse_ascii_date()

Parse a date in the “YYYY/MM/DD” format.

Args:

data (bytes): A date in the “YYYY/MM/DD” format.

Returns:

datetime: A Python datetime object.

parse_bi2_bin()

Return a parsed version of the Disc Header Information (“bi2.bin”) of the GCM.

Returns:

dict: A parsed version of the Disc Header Information (“bi2.bin”) of the GCM.

parse_boot_bin()

Return a parsed version of the Disk Header (“boot.bin”) of the GCM.

Returns:

dict: A parsed version of the Disk Header (“boot.bin”) of the GCM.

parse_fst(parent_path, fst, string_table_start)

Recursively parse the File System Table (FST).

Args:

fst_ind (int): This entry’s index in the FST.

parent_path (Path): The local Path of parent of this file/directory, or None if this is the root directory.

fst (bytes): The raw bytes of the FST.

string_table_start (int): Offset in the FST where the string table begins.

Returns:

dict: The root of the parsed FST.

class niemafs.IsoFS(file_obj, path=None)

Bases: FileSystem

Class to represent an ISO 9660 optical disc

detect_layout()

Detect physical sector size, user data offset, and user data size by validating the PVD at LBA 16.

get_boot_record()

Return the Boot Record (Volume Descriptor code 0) of the ISO.

Returns:

bytes: The Boot Record (Volume Descriptor code 0) of the ISO, or None if the ISO does not have one.

get_logical_block_size()

Return the ISO logical block size.

Returns:

int: The ISO logical block size in bytes.

get_physical_logical_block_size()

Return the ISO physical logical block size.

Returns:

int: The ISO physical logical block size.

get_primary_volume_descriptor()

Return the Primary Volume Descriptor (PVD; Volume Descriptor code 1) of the ISO.

Returns:

bytes: The Primary Volume Descriptor (PVD; Volume Descriptor code 1) of the ISO, or None if the ISO does not have one.

get_supplementary_volume_descriptor()

Return the Supplementary Volume Descriptor (Volume Descriptor code 2) of the ISO.

Returns:

bytes: The Supplementary Volume Descriptor (Volume Descriptor code 2) of the ISO, or None if the ISO does not have one.

get_system_area()

Return the System Area (logical sectors 0x00-0x0F = first 16 sectors) of the ISO.

Returns:

bytes: The System Area (first 16 ISO logical blocks).

get_user_data_offset()

Return the ISO user data offset.

Returns:

int: The ISO user data offset.

get_user_data_size()

Return the ISO user data size.

Returns:

int: The ISO user data size.

get_volume_descriptor_set_terminator()

Return the Volume Descriptor Set Terminator (Volume Descriptor code 0xFF = 255) of the ISO.

Returns:

bytes: The Volume Descriptor Set Terminator (Volume Descriptor code 0xFF = 255) of the ISO, or None if the ISO does not have one.

get_volume_descriptors()

Return the Volume Descriptors of the ISO.

Returns:

dict: Keys are Volume Descriptor Type codes, and values are bytes of the corresponding volume descriptor.

get_volume_partition_descriptor()

Return the Volume Partition Descriptor (Volume Descriptor code 3) of the ISO.

Returns:

bytes: The Volume Partition Descriptor (Volume Descriptor code 3) of the ISO, or None if the ISO does not have one.

looks_like_pvd(block: bytes) → bool

Validate the start of an ISO 9660 Volume Descriptor block.

Args:

block (bytes): The block to validate.

Returns:

bool: True if the block looks valid, otherwise False.

parse_boot_record()

Return a parsed version of the Boot Record of the ISO.

Returns:

dict: A parsed version of the Boot Record of the ISO, or None if the ISO does not have one.

parse_directory_datetime()

Parse a date/time in the `ISO 9660 directory record date/time format <https://wiki.osdev.org/ISO_9660#Directories>.`_

Args:

data (bytes): A date/time (exactly 7 bytes) in the ISO 9660 directory record date/time format.

Returns:

datetime: A Python datetime object.

parse_directory_record()

Parse an ISO 9660 directory record.

Args:

data (bytes): The raw bytes of the directory record.

Returns:

dict: The parsed directory record.

parse_primary_volume_descriptor()

Return a parsed version of the Primary Volume Descriptor (PVD) of the ISO.

Returns:

dict: A parsed version of the Primary Volume Descriptor (PVD) of the ISO, or None if the ISO does not have one.

parse_pvd_datetime()

Parse a date/time in the ISO 9660 Primary Volume Descriptor (PVD) date/time format.

Args:

data (bytes): A date/time (exactly 17 bytes) in the ISO 9660 PVD date/time format.

Returns:

datetime: A Python datetime object.

parse_volume_descriptor_set_terminator()

Return a parsed version of the Volume Descriptor Set Terminator of the ISO.

Returns:

dict: A parsed version of the Volume Descriptor Set Terminator of the ISO, or None if the ISO does not have one.

read_extent(lba, length)

Read bytes from the ISO extent starting at a specific LBA (in user-data LBAs).

Args:

lba: The first LBA of the read.

length (int): The number of bytes to read.

Returns:

bytes: The read data.

read_user_blocks(lba, count=1)

Read ISO logical blocks (user data blocks) starting at a specific LBA, returning concatenated user data.

Args:

lba (int): The first LBA of the read.

count: The number of ISO logical blocks to read.

Returns:

bytes: The read data.

tz_offset_to_datetime_str()

Convert an ISO 9660 timezone offset to a datetime format string

Args:

x (int): The ISO 9660 timezone offset.

Returns:

str: The datetime format string.

class niemafs.TarFS(file_obj, path=None)

Bases: FileSystem

Class to represent a TAR archive

class niemafs.TgcFS(file_obj, path=None)

Bases: FileSystem

Class to represent a Nintendo GameCube TGC image.

get_gcm()

Return the Embedded GCM of the TGC.

Args:

fix (bool): True to update the offsets of the embedded GCM data with their correct values based on the Header, otherwise False to return the raw embedded GCM data.

Returns:

bytes: The Embedded GCM of the TGC.

get_header()

Return the Header of the TGC.

Returns:

bytes: The Header of the TGC.

parse_header()

Return a parsed version of the Header of the TGC.

Returns:

dict: A parsed version of the Header of the TGC.

class niemafs.WiiFS(file_obj, path=None)

Bases: FileSystem

Class to represent a Nintendo Wii DVD.

get_header()

Return the Header of the Wii disc.

Returns:

bytes: The Header of the Wii disc.

get_partition_tables()

Return the Partition Tables of the Wii disc.

Returns:

list of bytes: The Partition Tables of the Wii disc.

get_region_info()

Return the Region Information of the Wii disc.

Returns:

bytes: The Region Information of the Wii disc.

get_volume_info()

Return the Volume (Partitions) Information of the Wii disc.

Returns:

bytes: The Volume (Partitions) Information of the Wii disc.

parse_header()

Return a parsed version of the Header of the Wii disc or partition.

Returns:

dict: A parsed version of the Header of the Wii disc or partition.

parse_partition_tables()

Return a parsed version of the Partition Tables of the Wii disc.

Returns:

list of dict: A parsed version of the Partition Tables

parse_region_info()

Return a parsed version of the Region Information of the Wii disc.

Returns:

dict: A parsed version of the Region Information of the Wii disc.

parse_ticket()

Return a parsed version of a Ticket of the Wii disc.

Args:

data (bytes): The raw Ticket data.

Returns:

dict: A parsed version of a Ticket of the Wii disc.

parse_volume_info()

Return a parsed version of the Volume (Partitions) Information of the Wii disc.

Returns:

list of dict: A parsed version of the Volume (Partitions) Information of the Wii disc.

class niemafs.ZipFS(file_obj, path=None)

Bases: FileSystem

Class to represent a ZIP archive

niemafs.clean_string(s)

Clean a string (binary or normal) by right-stripping 0x00 and spaces.

Args:

s (bytes): The ISO 9660 string to clean.

Returns:

str: The cleaned string.

niemafs.open_file(path, mode='rb', buffering=8388608, compresslevel=9)

Open a file for reading, writing, or appending. Automatically handles GZIP compression.

Args:

path (Path): The path of the file, or None for stdin/stdout.

mode (str): The mode in which to open the file.

buffering (int): The buffer size for buffered input/output.

Returns:

file-like object

niemafs.safename(s)

Convert a string into a version that is safe for a filename

Args:

s (str): The original string.

Returns:

str: A version of s that is safe for a filename.