PyLibMS 5.0.4__tar.gz → 5.0.5__tar.gz

{pylibms-5.0.4 → pylibms-5.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyLibMS
-Version: 5.0.4
+Version: 5.0.5
 Summary: Python library built for the libMessageStudio (LMS) proprietary file formats from Nintendo. Supports MSBT, MSBP, and MSBF.
 Author: AbdyyEee
 License-Expression: MIT

{pylibms-5.0.4 → pylibms-5.0.5}/PyLibMS.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: PyLibMS
-Version: 5.0.4
+Version: 5.0.5
 Summary: Python library built for the libMessageStudio (LMS) proprietary file formats from Nintendo. Supports MSBT, MSBP, and MSBF.
 Author: AbdyyEee
 License-Expression: MIT

{pylibms-5.0.4 → pylibms-5.0.5}/PyLibMS.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ lms/common/stream/fileinfo.py
 lms/common/stream/hashtable.py
 lms/common/stream/section.py
 lms/fileio/encoding.py
+lms/fileio/endian.py
 lms/fileio/io.py
 lms/flowchart/__init__.py
 lms/flowchart/flw3.py
@@ -35,6 +36,8 @@ lms/message/lms_messagetext.py
 lms/message/msbt.py
 lms/message/msbtentry.py
 lms/message/msbtio.py
+lms/message/umsbt.py
+lms/message/umsbtio.py
 lms/message/definitions/__init__.py
 lms/message/section/__init__.py
 lms/message/section/atr1.py

{pylibms-5.0.4 → pylibms-5.0.5}/lms/common/lms_fileinfo.py

@@ -1,11 +1,12 @@
 from dataclasses import dataclass
 
 from lms.fileio.encoding import FileEncoding
+from lms.fileio.io import FileEndian
 
 
 @dataclass
 class LMS_FileInfo:
-    is_big_endian: bool = False
+    endian: FileEndian = FileEndian.LITTLE
     encoding: FileEncoding = FileEncoding.UTF16
     version: int = 3
     section_count: int = 2

{pylibms-5.0.4 → pylibms-5.0.5}/lms/common/stream/fileinfo.py

@@ -1,12 +1,12 @@
 from lms.common import lms_exceptions
 from lms.common.lms_constants import (
-    BIG_ENDIAN_BOM,
     SECTION_DATA_START,
-    LITTLE_ENDIAN_BOM,
     SIZE_OFFSET, LMS_MINIMUM_VERSION,
+    LITTLE_ENDIAN_BOM, BIG_ENDIAN_BOM,
 )
 from lms.common.lms_fileinfo import LMS_FileInfo
 from lms.fileio.encoding import FileEncoding
+from lms.fileio.endian import FileEndian
 from lms.fileio.io import FileReader, FileWriter
 
 
@@ -19,9 +19,16 @@ def read_file_info(reader: FileReader, expected_magic: str) -> LMS_FileInfo:
             This file may not a valid LMS format or the wrong reading function was utilized."""
         )
 
-    is_big_endian = reader.read_bytes(2) == BIG_ENDIAN_BOM
-    reader.is_big_endian = is_big_endian
+    bom = reader.read_bytes(2)
 
+    if bom == LITTLE_ENDIAN_BOM:
+        endian = FileEndian.LITTLE
+    elif bom == BIG_ENDIAN_BOM:
+        endian = FileEndian.BIG
+    else:
+        raise ValueError(f"Invalid bom found in file '{bom}'!")
+
+    reader.endian = endian
     reader.skip(2)
 
     encoding = FileEncoding(reader.read_uint8())
@@ -48,7 +55,7 @@ def read_file_info(reader: FileReader, expected_magic: str) -> LMS_FileInfo:
     reader.seek(SECTION_DATA_START)
 
     return LMS_FileInfo(
-        is_big_endian,
+        endian,
         encoding,
         version,
         section_count,
@@ -56,13 +63,11 @@ def read_file_info(reader: FileReader, expected_magic: str) -> LMS_FileInfo:
 
 
 def write_file_info(writer: FileWriter, magic: str, file_info: LMS_FileInfo) -> None:
-    writer.is_big_endian = file_info.is_big_endian
+    writer.endian = file_info.endian
     writer.encoding = file_info.encoding
 
     writer.write_string(magic)
-    writer.write_bytes(
-        LITTLE_ENDIAN_BOM if not file_info.is_big_endian else BIG_ENDIAN_BOM
-    )
+    writer.write_bytes(file_info.endian.byte_order_mark)
     writer.write_bytes(b"\x00\x00")
 
     writer.write_uint8(file_info.encoding.value)

{pylibms-5.0.4 → pylibms-5.0.5}/lms/fileio/encoding.py

@@ -1,6 +1,8 @@
 from enum import IntEnum
 from typing import Literal
 
+from lms.fileio.endian import FileEndian
+
 
 class FileEncoding(IntEnum):
     """An enum that represents a file encoding."""
@@ -10,20 +12,16 @@ class FileEncoding(IntEnum):
     UTF32 = 0x02
 
     def to_string_format(
-        self, is_big_endian: bool = False
+            self, endian: FileEndian = FileEndian.LITTLE
     ) -> Literal["UTF-8", "UTF-16-BE", "UTF-16-LE", "UTF-32-BE", "UTF-32-LE"]:
         """Converts the FileEncoding to string format."""
         match self:
             case FileEncoding.UTF8:
                 return "UTF-8"
             case FileEncoding.UTF16:
-                if is_big_endian:
-                    return "UTF-16-BE"
-                return "UTF-16-LE"
+                return "UTF-16-BE" if endian is FileEndian.BIG else "UTF-16-LE"
             case FileEncoding.UTF32:
-                if is_big_endian:
-                    return "UTF-32-BE"
-                return "UTF-32-LE"
+                return "UTF-32-BE" if endian is FileEndian.BIG else "UTF-32-LE"
 
     @property
     def width(self) -> Literal[1, 2, 4]:

pylibms-5.0.5/lms/fileio/endian.py

@@ -0,0 +1,19 @@
+from enum import Enum
+from typing import Literal
+
+
+class FileEndian(Enum):
+    """An enum that represents a file endianness."""
+
+    LITTLE = 0
+    BIG = 1
+
+    @property
+    def string_name(self) -> Literal["little", "big"]:
+        """Name of the endian as a string."""
+        return self._name_.lower()
+
+    @property
+    def byte_order_mark(self) -> Literal[b"\xFF\xFE", b"\xFE\xFF"]:
+        """The BOM of the endian."""
+        return b"\xFF\xFE" if self is FileEndian.LITTLE else b"\xFE\xFF"

{pylibms-5.0.4 → pylibms-5.0.5}/lms/fileio/io.py

@@ -6,6 +6,7 @@ from typing import BinaryIO, Generator, Type
 
 from io import BytesIO, IOBase, TextIOBase
 from lms.fileio.encoding import FileEncoding
+from lms.fileio.endian import FileEndian
 
 PADDING_BYTE = b"\x00"
 
@@ -31,7 +32,7 @@ class StructBETypes(StrEnum):
 
 
 class FileReader:
-    def __init__(self, data: BinaryIO | bytes | bytearray | memoryview, big_endian: bool = False):
+    def __init__(self, data: BinaryIO | bytes | bytearray | memoryview, endian: FileEndian = FileEndian.LITTLE) -> None:
         self._stream: BinaryIO = None
 
         match data:
@@ -43,11 +44,11 @@ class FileReader:
                 raise TypeError("The stream provided is not valid!")
 
         self.encoding = FileEncoding.UTF8
-        self.is_big_endian = big_endian
+        self.endian = endian
 
     @property
     def datatypes(self) -> Type[StructLETypes | StructBETypes]:
-        return StructLETypes if not self.is_big_endian else StructBETypes
+        return StructLETypes if self.endian == FileEndian.LITTLE else StructBETypes
 
     def tell(self) -> int:
         return self._stream.tell()
@@ -110,25 +111,25 @@ class FileReader:
         string = b""
         while (raw_char := self.read_bytes(self.encoding.width)) != self.encoding.terminator:
             string += raw_char
-        return string.decode(self.encoding.to_string_format(self.is_big_endian))
+        return string.decode(self.encoding.to_string_format(self.endian))
 
     def read_len_string_encoded(self):
         self.align(self.encoding.width)
         length = self.read_uint16()
         return self.read_bytes(length).decode(
-            self.encoding.to_string_format(self.is_big_endian)
+            self.encoding.to_string_format(self.endian)
         )
 
 
 class FileWriter:
-    def __init__(self, encoding: FileEncoding):
+    def __init__(self, encoding: FileEncoding = FileEncoding.UTF8, endian: FileEndian = FileEndian.LITTLE) -> None:
         self.data = BytesIO(b"")
         self.encoding = encoding
-        self.is_big_endian = False
+        self.endian = endian
 
     @property
     def datatypes(self) -> Type[StructLETypes | StructBETypes]:
-        return StructLETypes if not self.is_big_endian else StructBETypes
+        return StructLETypes if self.endian == FileEndian.LITTLE else StructBETypes
 
     def skip(self, length: int) -> None:
         self.data.seek(length, 1)
@@ -186,7 +187,7 @@ class FileWriter:
 
     def write_encoded_string(self, string: str, terminate: bool = True) -> None:
         self.write_bytes(
-            string.encode(self.encoding.to_string_format(self.is_big_endian))
+            string.encode(self.encoding.to_string_format(self.endian))
         )
         if terminate:
             self.write_bytes(b"\x00" * self.encoding.width)

{pylibms-5.0.4 → pylibms-5.0.5}/lms/flowchart/msbf.py

@@ -3,6 +3,7 @@ from typing import Mapping, Iterator
 
 from lms.common.lms_fileinfo import LMS_FileInfo
 from lms.fileio.encoding import FileEncoding
+from lms.fileio.endian import FileEndian
 from lms.flowchart.definitions.node import LMS_EntryNode, LMS_JumpNode, LMS_BranchNode, LMS_BaseNode
 
 
@@ -52,7 +53,7 @@ class MSBF:
     @classmethod
     def new(
             cls,
-            is_big_endian: bool = False,
+            endian: FileEndian = FileEndian.LITTLE,
             encoding: FileEncoding = FileEncoding.UTF16,
             version: int = 3,
             section_count: int = 2,
@@ -60,13 +61,13 @@ class MSBF:
         """
         Create a new MSBF instance.
 
-        :param is_big_endian: if the file is big endian.
+        :param endian: the endian of the file.
         :param encoding: the file encoding.
         :param version: the file version.
         :param section_count: the number of sections.
 
         """
-        return MSBF(LMS_FileInfo(is_big_endian, encoding, version, section_count))
+        return MSBF(LMS_FileInfo(endian, encoding, version, section_count))
 
     @property
     def info(self) -> LMS_FileInfo:

{pylibms-5.0.4 → pylibms-5.0.5}/lms/flowchart/msbfio.py

@@ -63,6 +63,7 @@ def read_msbf(
     >>> msbf = read_msbf(stream)
     """
     reader = FileReader(stream)
+
     file_info = read_file_info(reader, MSBF.MAGIC)
 
     if msbt is not None and msbt_files:

{pylibms-5.0.4 → pylibms-5.0.5}/lms/message/lms_messagetext.py

@@ -177,6 +177,7 @@ class LMS_MessageText:
 
     def _set_segments(self, text: str) -> None:
         self._segments = []
+
         for part in self.TAG_FORMAT.split(text):
             if bool(re.match(self.TAG_FORMAT, part)):
                 self.append_tag_string(part)

{pylibms-5.0.4 → pylibms-5.0.5}/lms/message/msbt.py

@@ -1,8 +1,10 @@
-from typing import overload
+from types import MappingProxyType
+from typing import overload, Mapping
 
 from lms.common.field.lms_field import LMS_FieldMap
 from lms.common.lms_fileinfo import LMS_FileInfo
 from lms.fileio.encoding import FileEncoding
+from lms.fileio.endian import FileEndian
 from lms.message.lms_messagetext import LMS_MessageText
 from lms.message.msbtentry import MSBTEntry
 from lms.titleconfig.definitions.attribute import AttributeConfig
@@ -56,9 +58,7 @@ class MSBT:
         self._unsupported_section_map = unsupported_section_map or {}
 
         # Store the section list so that the order of any and all sections is preserved when writing
-        self._section_list: list[str] = section_list or [
-            "LBL1" if not uses_nli1 else "NLI1"
-        ]
+        self._section_list: list[str] = section_list
 
         self._attribute_config = attribute_config
         self._tag_config = tag_config
@@ -91,7 +91,7 @@ class MSBT:
             uses_nli1: bool = False,
             attribute_config: AttributeConfig | None = None,
             tag_config: TagConfig | None = None,
-            is_big_endian: bool = False,
+            endian: FileEndian = FileEndian.LITTLE,
             encoding: FileEncoding = FileEncoding.UTF16,
             version: int = 3,
             section_count: int = 2,
@@ -102,7 +102,7 @@ class MSBT:
         :param uses_nli1: flag to determine if to use nli1 section for labels.
         :param attribute_config: the attribute config object
         :param tag_config: the tag config object
-        :param is_big_endian: if the file is big endian.
+        :param endian: if the file is big endian.
         :param encoding: the file encoding.
         :param version: the file version.
         :param section_count: the number of sections.
@@ -113,7 +113,8 @@ class MSBT:
         See https://github.com/AbdyyEee/PylibMS/wiki/MSBT#creating-a-msbt
         """
         return MSBT(
-            LMS_FileInfo(is_big_endian, encoding, version, section_count),
+            LMS_FileInfo(endian, encoding, version, section_count),
+            section_list=["LBL1" if not uses_nli1 else "NLI1", "TXT2"],
             uses_nli1=uses_nli1,
             attribute_config=attribute_config,
             tag_config=tag_config,
@@ -129,6 +130,11 @@ class MSBT:
         """Tuple of all the MSBT entries."""
         return tuple(self._entries)
 
+    @property
+    def label_map(self) -> Mapping[str, MSBTEntry]:
+        """Mapping of all labels to MSBT entries."""
+        return MappingProxyType(self._label_map)
+
     @property
     def section_list(self) -> tuple[str, ...]:
         """The list of sections with order preserved."""
@@ -160,10 +166,14 @@ class MSBT:
         :param label: the label to check."""
         return label in self._label_map
 
+    # Backwards compatibility just in case
+    # Recommended to use accessors MSBT[index] or MSBT[label]
     def get_entry_by_index(self, index: int) -> MSBTEntry:
         """
         Retrieves an entry given its index. Supports negative indexing.
 
+        Recommended to use ``MSBT[index]`` over this function.
+
         :param index: the index of the entry.
         """
         if not (-len(self._entries) <= index < len(self._entries)):
@@ -175,6 +185,8 @@ class MSBT:
         """
         Retrieves an entry given its name.
 
+        Recommended to use ``MSBT[label]`` over this function.
+
         :param label: the label name for the entry.
         """
         if label not in self._label_map:
@@ -203,6 +215,9 @@ class MSBT:
                     f"Entry '{entry.name}' can't be added with no attributes when attributes already exist!"
                 )
         elif entry.attribute is not None:
+            if self._entries:
+                raise ValueError("All entries must have attributes tied to them!")
+
             self._section_list.insert(self.ATR1_INDEX, "ATR1")
             self._info.section_count += 1
 

{pylibms-5.0.4 → pylibms-5.0.5}/lms/message/msbtentry.py

@@ -8,12 +8,12 @@ class MSBTEntry:
     """A class that represents an entry in a MSBT file."""
 
     def __init__(
-        self,
-        name: str,
-        *,
-        message: LMS_MessageText | str | None = "",
-        attribute: LMS_FieldMap | bytes | None = None,
-        style_index: int | None = None,
+            self,
+            name: str,
+            *,
+            message: LMS_MessageText | str | None = "",
+            attribute: LMS_FieldMap | bytes | None = None,
+            style_index: int | None = None,
     ):
         self.name = name
 
@@ -37,7 +37,7 @@ class MSBTEntry:
         self.style_index = style_index
 
     @property
-    def message(self) -> LMS_MessageText | None:
+    def message(self) -> LMS_MessageText:
         """The message object for the instance."""
         return self._message
 
@@ -64,10 +64,10 @@ class MSBTEntry:
 
     @classmethod
     def from_dict(
-        cls,
-        data: dict,
-        attribute_config: AttributeConfig | None = None,
-        tag_config: TagConfig | None = None,
+            cls,
+            data: dict,
+            attribute_config: AttributeConfig | None = None,
+            tag_config: TagConfig | None = None,
     ):
         """
         Creates a MSBTEntry from a dictionary object.

{pylibms-5.0.4 → pylibms-5.0.5}/lms/message/msbtio.py

@@ -2,7 +2,8 @@
 IO interface for ``MSBT`` files.
 """
 import os
-from typing import BinaryIO
+from types import MappingProxyType
+from typing import BinaryIO, Mapping
 
 from lms.common import lms_exceptions
 from lms.common.stream.fileinfo import read_file_info, write_file_info, write_file_size
@@ -23,6 +24,8 @@ from lms.titleconfig.config import AttributeConfig, TagConfig
 
 __all__ = ("read_msbt_path", "read_msbt_directory", "read_msbt", "write_msbt", "write_msbt_path")
 
+MSBT_EXTENSION = ".msbt"
+
 
 def read_msbt_path(
         file_path: str | os.PathLike[str],
@@ -60,11 +63,12 @@ def read_msbt_directory(directory: str | os.PathLike[str], *,
                         attribute_config: AttributeConfig | None = None,
                         tag_config: TagConfig | None = None,
                         suppress_tag_errors: bool = False,
-                        ignore_extensions: bool = False) -> tuple[MSBT, ...]:
+                        ignore_extensions: bool = False) -> Mapping[str, MSBT]:
     """
-    Reads and retrieves MSBT all MSBT files from a given directory.
+    Reads and retrieves all MSBT files from a given directory.
 
-    :param directory: directory of MSBT files. All files must have the `.msbt` extension.
+    :param directory: directory of MSBT files. All files must have the `.msbt` extension (unless ``ignore_extensions``
+    is True)
     :param attribute_config: the attribute config to use for decoding attributes.
     :param tag_config: the tag config to use for decoding tags.
     :param suppress_tag_errors: when a tag config is used, suppress any errors while reading decoded tags.
@@ -75,19 +79,21 @@ def read_msbt_directory(directory: str | os.PathLike[str], *,
     =====
     >>> msbt = read_msbt_directory("path/to/directory")
     """
-    files: list[MSBT] = []
+    files: dict[str, MSBT] = {}
 
     for file in os.listdir(directory):
-        if not file.endswith(".msbt") and not ignore_extensions:
-            raise ValueError("This directory contains a non-MSBT file. Only directories with MSBT files can be used!")
-
-        files.append(msbt := read_msbt_path(file_path := os.path.join(directory, file),
-                                            attribute_config=attribute_config,
-                                            tag_config=tag_config, suppress_tag_errors=suppress_tag_errors))
-
-        msbt.filename = os.path.basename(file_path)
-
-    return tuple(files)
+        if not file.endswith(MSBT_EXTENSION) and not ignore_extensions:
+            raise ValueError("This directory contains a non-MSBT file. "
+                             "Only directories with MSBT files can be used! Set ignore_extensions to True to ignore"
+                             "this error.")
+
+        msbt = read_msbt_path(os.path.join(directory, file),
+                              attribute_config=attribute_config,
+                              tag_config=tag_config, suppress_tag_errors=suppress_tag_errors)
+        msbt.filename = file
+        files[file] = msbt
+
+    return MappingProxyType(files)
 
 
 def read_msbt(

{pylibms-5.0.4 → pylibms-5.0.5}/lms/message/section/txt2.py

@@ -6,15 +6,15 @@ from lms.titleconfig.definitions.tags import TagConfig
 
 
 def read_txt2(
-    reader: FileReader, config: TagConfig | None, suppress_tag_errors: bool
+        reader: FileReader, config: TagConfig | None, suppress_tag_errors: bool
 ) -> list[LMS_MessageText]:
     encoding = reader.encoding
 
     messages = []
     message_count = reader.read_uint32()
 
-    encoding_format = encoding.to_string_format(reader.is_big_endian)
-    tag_start, tag_close = get_tag_indicator(encoding, reader.is_big_endian)
+    encoding_format = encoding.to_string_format(reader.endian)
+    tag_start, tag_close = get_tag_indicator(encoding, reader.endian)
 
     for offset in reader.read_offset_array(message_count):
         reader.seek(offset)

{pylibms-5.0.4 → pylibms-5.0.5}/lms/message/tag/io/tag_io.py

@@ -1,4 +1,5 @@
 from lms.fileio.encoding import FileEncoding
+from lms.fileio.endian import FileEndian
 from lms.fileio.io import FileReader, FileWriter
 from lms.message.tag.io.param_io import (
     read_decoded_parameters,
@@ -13,12 +14,12 @@ from lms.titleconfig.definitions.tags import TagConfig, TagDefinition
 TAG_PADDING_BYTE = b"\xcd"
 
 
-def get_tag_indicator(encoding: FileEncoding, is_big_endian: bool):
+def get_tag_indicator(encoding: FileEncoding, endian: FileEndian):
     start_indicator = int.to_bytes(
-        0x0E, encoding.width, "little" if not is_big_endian else "big"
+        0x0E, encoding.width, endian.string_name
     )
     closing_indicator = int.to_bytes(
-        0x0F, encoding.width, "little" if not is_big_endian else "big"
+        0x0F, encoding.width, endian.string_name
     )
     return start_indicator, closing_indicator
 
@@ -95,7 +96,7 @@ def _read_decoded_tag(
 
 def write_tag(writer: FileWriter, tag: LMS_ControlTag) -> None:
     start_indicator, close_indicator = get_tag_indicator(
-        writer.encoding, writer.is_big_endian
+        writer.encoding, writer.endian
     )
     writer.write_bytes(start_indicator if not tag.is_closing else close_indicator)
 

pylibms-5.0.5/lms/message/umsbt.py

@@ -0,0 +1,91 @@
+from types import MappingProxyType
+from typing import overload, Mapping, Sequence, Iterator
+
+from lms.message.msbt import MSBT
+
+
+class UMSBT:
+    """Class that represents a UMSBT file, an archive for MSBT files."""
+
+    def __init__(self, files: Sequence[MSBT] | None = None) -> None:
+        self._files = list(files) if files is not None else []
+
+        for file in self._files:
+            if not isinstance(file, MSBT):
+                raise TypeError("Only MSBTs are allowed for UMSBT archives!")
+
+        self._realign_filenames()
+
+    @overload
+    def __getitem__(self, index: int) -> MSBT:
+        ...
+
+    @overload
+    def __getitem__(self, label: str) -> MSBT:
+        ...
+
+    def __getitem__(self, value: int | str) -> MSBT:
+        if isinstance(value, str):
+            return self.file_map[value]
+
+        return self._files[value]
+
+    def __len__(self) -> int:
+        return len(self._files)
+
+    def __iter__(self) -> Iterator[MSBT]:
+        return iter(self._files)
+
+    @property
+    def files(self) -> tuple[MSBT, ...]:
+        """Maps of files tied to this instance."""
+        return tuple(self._files)
+
+    @property
+    def file_map(self) -> Mapping[str, MSBT]:
+        """Maps of files tied to this instance."""
+        return MappingProxyType({msbt.filename: msbt for msbt in self._files})
+
+    def add_msbt(self, msbt: MSBT) -> None:
+        """
+        Adds a MSBT to the UMSBT archive.
+
+        :param msbt: the msbt to add.
+        """
+        self._files.append(msbt)
+        self._realign_filenames()
+
+    def insert_msbt(self, position: int, msbt: MSBT) -> None:
+        """
+        Inserts a MSBT in the archive at a specific index
+
+        :param position: position of the MSBT to insert.
+        :param msbt: the msbt to insert.
+        """
+        self._files.insert(position, msbt)
+        self._realign_filenames()
+
+    @overload
+    def remove_msbt(self, msbt: MSBT) -> None:
+        ...
+
+    @overload
+    def remove_msbt(self, msbt: int) -> None:
+        ...
+
+    def remove_msbt(self, msbt: MSBT | int) -> None:
+        """
+        Deletes a MSBT from the UMSBT archive.
+
+        :param msbt: the msbt object or index to remove.
+        """
+        if isinstance(msbt, MSBT):
+            self._files.remove(msbt)
+        else:
+            del self._files[msbt]
+
+        self._realign_filenames()
+
+    def _realign_filenames(self) -> None:
+        for i, msbt in enumerate(self._files):
+            msbt.filename = f"{i}.msbt"

pylibms-5.0.5/lms/message/umsbtio.py

@@ -0,0 +1,183 @@
+"""
+IO interface for ``UMSBT`` files.
+"""
+import os
+from typing import Mapping, BinaryIO
+
+from lms.common import lms_exceptions
+from lms.fileio.io import FileReader, FileWriter
+from lms.message.msbt import MSBT
+from lms.message.msbtio import read_msbt, write_msbt
+from lms.message.umsbt import UMSBT
+from lms.titleconfig.definitions.attribute import AttributeConfig
+from lms.titleconfig.definitions.tags import TagConfig
+
+__all__ = ("read_umsbt_path", "read_umsbt_directory", "read_umsbt", "write_umsbt_path", "write_umsbt")
+
+UMSBT_EXTENSION = ".umsbt"
+UMSBT_ALIGNMENT = 16
+SIZE_PER_METADATA = 8
+
+
+def read_umsbt_path(
+        file_path: str | os.PathLike[str], *,
+        attribute_config: AttributeConfig | None = None,
+        tag_config: TagConfig | None = None,
+        suppress_tag_errors: bool = False,
+) -> UMSBT:
+    """
+    Reads and retrieves a UMSBT file from a given path.
+
+    :param file_path: the path to the UMSBT file.
+    :param attribute_config: the attribute config to use for decoding attributes.
+    :param tag_config: the tag config to use for decoding tags.
+    :param suppress_tag_errors: when a tag config is used, suppress any errors while reading decoded tags.
+
+    =====
+    Usage
+    =====
+    >>> umsbt = read_umsbt_path("path/to/file.umsbt")
+    """
+    with open(file_path, "rb") as stream:
+        umsbt = read_umsbt(stream,
+                           attribute_config=attribute_config,
+                           tag_config=tag_config,
+                           suppress_tag_errors=suppress_tag_errors)
+
+    return umsbt
+
+
+def read_umsbt_directory(directory: str | os.PathLike[str], *,
+                         attribute_config: AttributeConfig | None = None,
+                         tag_config: TagConfig | None = None,
+                         suppress_tag_errors: bool = False,
+                         ignore_extensions: bool = False) -> Mapping[str, tuple[MSBT, ...]]:
+    """
+    Reads and retrieves all UMSBT files from a given directory.
+
+    :param directory: directory of UMSBT files. All files must have the `.umsbt` extension (unless ``ignore_extensions``
+    is True)
+    :param attribute_config: the attribute config to use for decoding attributes.
+    :param tag_config: the tag config to use for decoding tags.
+    :param suppress_tag_errors: when a tag config is used, suppress any errors while reading decoded tags.
+    :param ignore_extensions: ignore the extensions in the directory.
+
+    =====
+    Usage
+    =====
+    >>> umsbts = read_msbt_directory("path/to/directory")
+    """
+    files: dict[str, tuple[MSBT, ...]] = {}
+
+    for file in os.listdir(directory):
+        if not file.endswith(UMSBT_EXTENSION) and not ignore_extensions:
+            raise ValueError("This directory contains a non-UMSBT file. "
+                             "Only directories with UMSBT files can be used! Set ignore_extensions to True to ignore"
+                             "this error.")
+
+        umsbt = read_umsbt_path(os.path.join(directory, file),
+                                attribute_config=attribute_config,
+                                tag_config=tag_config, suppress_tag_errors=suppress_tag_errors)
+        files[os.path.basename(file)] = umsbt
+
+    return files
+
+
+def read_umsbt(
+        stream: BinaryIO | bytes, *,
+        attribute_config: AttributeConfig | None = None,
+        tag_config: TagConfig | None = None,
+        suppress_tag_errors: bool = False,
+) -> UMSBT:
+    """
+    Reads and retrieves a UMSBT file from a specified stream.
+
+    :param stream: an ``IOBase``, ``BytesIO``, ``memoryview``, or ``bytes`` object.
+    :param attribute_config: the attribute config to use for decoding attributes.
+    :param tag_config: the tag config to use for decoding tags.
+    :param suppress_tag_errors: when a tag config is used, suppress any errors while reading decoded tags.
+
+    =====
+    Usage
+    =====
+    >>> umsbt = read_umsbt(stream)
+    """
+    reader = FileReader(stream)
+    data_start = reader.read_uint32()
+
+    offsets, sizes = [], []
+
+    reader.seek(0)
+    while reader.tell() < data_start:
+        offset, size = reader.read_uint32(), reader.read_uint32()
+
+        # Reached padding section
+        if offset == 0 and size == 0:
+            break
+
+        offsets.append(offset)
+        sizes.append(size)
+
+    files = []
+    for i, (offset, size) in enumerate(zip(offsets, sizes)):
+        reader.seek(offset)
+        files.append(read_msbt(reader.read_bytes(size),
+                               attribute_config=attribute_config,
+                               tag_config=tag_config,
+                               suppress_tag_errors=suppress_tag_errors))
+
+    return UMSBT(files)
+
+
+def write_umsbt_path(file_path: str | os.PathLike[str], file: UMSBT) -> None:
+    """
+    Writes a UMSBT file to a given file path. If the target path does not exist, it will be created.
+
+    :param file_path: the path to write the file to.
+    :param file: the UMSBT file object.
+
+    =====
+    Usage
+    =====
+    >>> write_umsbt_path("path/to/file.umsbt", umsbt)
+    """
+    with open(file_path, "wb") as stream:
+        data = write_umsbt(file)
+        stream.write(data)
+
+
+def write_umsbt(file: UMSBT) -> bytes:
+    """
+    Writes a UMSBT file and returns the data.
+
+    :param file: a UMSBT object.
+
+    =====
+    Usage
+    =====
+    >>> data = write_umsbt(umsbt)
+    """
+    if not isinstance(file, UMSBT):
+        raise lms_exceptions.LMS_Error(
+            f"File provided is not valid. Expected UMSBT got {type(file)}."
+        )
+
+    writer = FileWriter()
+    msbt_count = len(file)
+    writer.write_bytes(b"\x00" * (msbt_count * SIZE_PER_METADATA))
+
+    writer.write_alignment(b"\x00", UMSBT_ALIGNMENT)
+    writer.write_bytes(b"\x00" * UMSBT_ALIGNMENT)
+
+    for i, msbt in enumerate(file):
+        offset = writer.tell()
+        data = write_msbt(msbt)
+        writer.write_bytes(data)
+        last_position = writer.tell()
+
+        writer.seek(i * SIZE_PER_METADATA)
+        writer.write_uint32(offset)
+        writer.write_uint32(len(data))
+        writer.seek(last_position)
+
+    return writer.get_data()

{pylibms-5.0.4 → pylibms-5.0.5}/lms/project/msbpread.py

@@ -50,6 +50,7 @@ def read_msbp(stream: BinaryIO | bytes) -> MSBP:
     >>> msbp = read_msbp(stream)
     """
     reader = FileReader(stream)
+
     file_info = read_file_info(reader, MSBP.MAGIC)
 
     colors = ()

{pylibms-5.0.4 → pylibms-5.0.5}/pyproject.toml

@@ -7,7 +7,7 @@ include = ["lms*"]
 
 [project]
 name = "PyLibMS"
-version = "5.0.4"
+version = "5.0.5"
 requires-python = ">=3.11"
 description = "Python library built for the libMessageStudio (LMS) proprietary file formats from Nintendo. Supports MSBT, MSBP, and MSBF."
 readme = "README.md"