PyLibMS 3.2.6__tar.gz → 3.3__tar.gz

{pylibms-3.2.6 → pylibms-3.3}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: PyLibMS
-Version: 3.2.6
-Summary: Python library built for the libMessageStudio (LMS) proprietary file formats from Nintendo. Supports MSBT, MSBP, and MSBF.
+Version: 3.3
+Summary: Python library built for the libMessageStudio (LMS) proprietary file formats from Nintendo. Supports MSBT, MSBP, and soon to be MSBF.
 Author: AbdyyEee
 License: Copyright 2025 AbdyyEee
         

{pylibms-3.2.6 → pylibms-3.3}/PyLibMS.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: PyLibMS
-Version: 3.2.6
-Summary: Python library built for the libMessageStudio (LMS) proprietary file formats from Nintendo. Supports MSBT, MSBP, and MSBF.
+Version: 3.3
+Summary: Python library built for the libMessageStudio (LMS) proprietary file formats from Nintendo. Supports MSBT, MSBP, and soon to be MSBF.
 Author: AbdyyEee
 License: Copyright 2025 AbdyyEee
         

{pylibms-3.2.6 → pylibms-3.3}/PyLibMS.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ lms/message/definitions/field/io.py
 lms/message/definitions/field/lms_field.py
 lms/message/section/__init__.py
 lms/message/section/atr1.py
+lms/message/section/nli1.py
 lms/message/section/tsy1.py
 lms/message/section/txt2.py
 lms/message/tag/__init__.py

{pylibms-3.2.6 → pylibms-3.3}/lms/common/stream/fileinfo.py

@@ -13,7 +13,8 @@ def read_file_info(reader: FileReader, expected_magic: str) -> LMS_FileInfo:
 
     if magic != expected_magic:
         raise lms_exceptions.LMS_UnexpectedMagicError(
-            f"Invalid magic!' Expected {expected_magic}', got '{magic}'."
+            f"""Invalid magic!' Expected {expected_magic}', got '{magic}'.
+            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

{pylibms-3.2.6 → pylibms-3.3}/lms/common/stream/section.py

@@ -4,7 +4,7 @@ from lms.fileio.io import FileReader, FileWriter
 
 
 def read_section_data(
-    reader: FileReader, section_count: int
+        reader: FileReader, section_count: int
 ) -> Generator[tuple[str, int], Any, None]:
     reader.seek(0x20)
     for _ in range(section_count):
@@ -21,11 +21,11 @@ def read_section_data(
 
 
 def write_section(
-    writer: FileWriter,
-    magic: str,
-    section_call: Callable,
-    data: list[Any],
-    *write_arguments: Any,
+        writer: FileWriter,
+        magic: str,
+        section_call: Callable,
+        data: list[Any],
+        *write_arguments: Any,
 ) -> None:
     writer.write_string(magic)
     size_offset = writer.tell()

{pylibms-3.2.6 → pylibms-3.3}/lms/fileio/encoding.py

@@ -10,7 +10,7 @@ class FileEncoding(IntEnum):
     UTF32 = 0x02
 
     def to_string_format(
-        self, is_big_endian: bool = False
+            self, is_big_endian: bool = False
     ) -> Literal["UTF-8", "UTF-16-BE", "UTF-16-LE", "UTF-32-BE", "UTF-32-LE"]:
         """Converts the FileEncoding to string format."""
         match self:

{pylibms-3.2.6 → pylibms-3.3}/lms/fileio/io.py

@@ -1,9 +1,9 @@
 from __future__ import annotations
 
 import struct
-from io import BytesIO, IOBase
 from typing import BinaryIO, Generator
 
+from io import BytesIO, IOBase
 from lms.fileio.encoding import FileEncoding
 
 STRUCT_TYPES = {
@@ -96,7 +96,7 @@ class FileReader:
     def read_encoded_string(self):
         message = b""
         while (
-            raw_char := self.read_bytes(self.encoding.width)
+                raw_char := self.read_bytes(self.encoding.width)
         ) != self.encoding.terminator:
             message += raw_char
         return message.decode(self.encoding.to_string_format(self.is_big_endian))

{pylibms-3.2.6 → pylibms-3.3}/lms/message/definitions/field/lms_field.py

@@ -9,7 +9,6 @@ from lms.titleconfig.definitions.value import ValueDefinition
 FLOAT_MIN = 1.17549435e-38
 FLOAT_MAX = 3.4028235e38
 
-
 type FieldValue = int | str | float | bool | bytes
 
 
@@ -83,7 +82,7 @@ class LMS_Field:
     """
 
     def __init__(
-        self, value: int | str | float | bytes | bool, definition: ValueDefinition
+            self, value: int | str | float | bytes | bool, definition: ValueDefinition
     ):
         _verify_value(value, definition)
         self._definition = definition
@@ -126,7 +125,7 @@ class LMS_Field:
 
 
 def _verify_value(
-    value: int | str | float | bytes | bool, definition: ValueDefinition
+        value: int | str | float | bytes | bool, definition: ValueDefinition
 ) -> None:
     datatype = definition.datatype
 
@@ -155,7 +154,7 @@ def _verify_value(
                 max_value = 2 ** (bits - 1)
                 min_value = -max_value
             else:
-                min_value, max_value = 0, (2**bits) - 1
+                min_value, max_value = 0, (2 ** bits) - 1
 
             _verify_number_is_in_range(value, min_value, max_value, definition)
             return
@@ -166,10 +165,10 @@ def _verify_value(
 
 
 def _verify_number_is_in_range(
-    value: int | float,
-    min_value: int | float,
-    max_value: int | float,
-    definition: ValueDefinition,
+        value: int | float,
+        min_value: int | float,
+        max_value: int | float,
+        definition: ValueDefinition,
 ):
     if not min_value <= value <= max_value:
         raise ValueError(

{pylibms-3.2.6 → pylibms-3.3}/lms/message/definitions/lms_messagetext.py

@@ -3,6 +3,7 @@ import re
 from lms.message.definitions.field.lms_field import LMS_FieldMap
 from lms.message.tag.lms_tag import (LMS_ControlTag, LMS_DecodedTag,
                                      LMS_EncodedTag, is_tag)
+from lms.message.tag.lms_tagexceptions import LMS_TagForbiddenParametersError
 from lms.titleconfig.config import TagConfig
 
 
@@ -12,9 +13,9 @@ class LMS_MessageText:
     TAG_FORMAT = re.compile(r"(\[[^]]+])")
 
     def __init__(
-        self,
-        message: str | list[str | LMS_ControlTag],
-        tag_config: TagConfig | None = None,
+            self,
+            message: str | list[str | LMS_ControlTag],
+            tag_config: TagConfig | None = None,
     ):
         self._tag_config = tag_config
 
@@ -59,22 +60,26 @@ class LMS_MessageText:
         return positions
 
     def append_encoded_tag(
-        self, group_id: int, tag_index: int, *parameters: str, is_closing: bool = False
+            self, group_id: int, tag_index: int, *parameters: int, is_closing: bool = False
     ) -> LMS_EncodedTag:
         """
         Appends an encoded tag to the current message and returns that tag.
 
         :param group_id: the group index.
         :param tag_index: the index of the tag in the group.
-        :param parameters: args of hex strings.
+        :param parameters: any amount of integer parameters.
         :param is_closing: whether the tag is closing or not.
 
-        Example
-        ------
+        =====
+        Usage
+        =====
         >>> message = LMS_MessageText("Text")
-        >>> message.append_encoded_tag(0, 3, "00", "23", "43", "32")
+        >>> message.append_encoded_tag(0, 3, 0x00, 0x23, 0x43, 0x32)
         """
         if is_closing:
+            if parameters:
+                raise LMS_TagForbiddenParametersError("There may not be parameters for closing tags!")
+
             tag = LMS_EncodedTag(group_id, tag_index, is_closing=True)
         else:
             tag = LMS_EncodedTag(
@@ -85,22 +90,23 @@ class LMS_MessageText:
         return tag
 
     def append_decoded_tag(
-        self,
-        group_name: str,
-        tag_name: str,
-        is_closing: bool = False,
-        **parameters: int | str | float | bool | bytes,
+            self,
+            group_name: str,
+            tag_name: str,
+            is_closing: bool = False,
+            **parameters: int | str | float | bool | bytes,
     ) -> LMS_DecodedTag:
         """
         Appends a decoded tag to the current message and returns that tag.
 
         :param group_name: the group name.
-        :param tag_name: the tag name.:
+        :param tag_name: the tag name.
         :param is_closing: whether the tag is closing or not.
         :param parameters: keyword arguments of parameters mapped to their value.
 
-        Example
-        -------
+        =====
+        Usage
+        =====
         >>> message = LMS_MessageText("Text")
         >>> message.append_decoded_tag("Mii", "Nickname", buffer=1, type="Voice", conversion="None")
         """
@@ -109,15 +115,19 @@ class LMS_MessageText:
 
         definition = self._tag_config.get_definition_by_names(group_name, tag_name)
 
-        if not parameters:
-            tag = LMS_DecodedTag(definition)
-        else:
-            param_map = LMS_FieldMap.from_dict(parameters, definition.parameters)
+        if is_closing:
+            if parameters:
+                raise LMS_TagForbiddenParametersError("There may not be parameters for closing tags!")
 
-            if is_closing:
-                tag = LMS_DecodedTag(definition, is_closing=True)
-            else:
-                tag = LMS_DecodedTag(definition, param_map)
+            tag = LMS_DecodedTag(definition, is_closing=True)
+            self._parts.append(tag)
+            return tag
+
+        if parameters:
+            param_map = LMS_FieldMap.from_dict(parameters, definition.parameters)
+            tag = LMS_DecodedTag(definition, param_map)
+        else:
+            tag = LMS_DecodedTag(definition)
 
         self._parts.append(tag)
         return tag
@@ -127,15 +137,26 @@ class LMS_MessageText:
         Appends a tag to the current message given a string.
 
         :param tag: the tag string.
+
+        If the tag provided is an encoded tag and the amount of parameters is an odd number, padding
+        will automatically be appended.
+
+        =====
+        Usage
+        =====
+        >>> tag = message.append_tag_string('[1:3 00-00-00-CD]')
+        >>> tag = message.append_tag_string('[/2:3]')
+        >>> tag = message.append_tag_string('[Reference:SpecialProduct buffer="0" type="Name" sp="Plural"]']
+        >>> tag = message.append_tag_string('[/Edward:ToLowerRange]')
         """
         if re.fullmatch(LMS_DecodedTag.TAG_FORMAT, tag):
             if self._tag_config is None:
-                raise ValueError("TagConfig is required to append decoded tags.")
+                raise ValueError("TagConfig is required to append decoded tags!")
             tag_obj = LMS_DecodedTag.from_string(tag, self._tag_config)
         elif re.fullmatch(LMS_EncodedTag.TAG_FORMAT, tag):
             tag_obj = LMS_EncodedTag.from_string(tag)
         else:
-            raise ValueError(f"Invalid format for tag '{tag}'.")
+            raise ValueError(f"Invalid format in tag '{tag}'.")
 
         self._parts.append(tag_obj)
         return tag_obj

{pylibms-3.2.6 → pylibms-3.3}/lms/message/msbt.py

@@ -1,30 +1,32 @@
 from lms.common.lms_fileinfo import LMS_FileInfo
+from lms.fileio.encoding import FileEncoding
 from lms.message.msbtentry import MSBTEntry
 from lms.titleconfig.definitions.attribute import AttributeConfig
 from lms.titleconfig.definitions.tags import TagConfig
-from lms.fileio.encoding import FileEncoding
 
 
 class MSBT:
     """
     A class that represents a MSBT file.
 
-    https://nintendo-formats.com/libs/lms/msbt.html.
+    https://nintendo-formats.com/libs/lms/msbt.html
     """
 
     MAGIC = "MsgStdBn"
 
-    # While 101 is the default slot count for LBL1 sections in a MSBT
-    # The value may be overridden at the instance level as some games alter the value
     DEFAULT_SLOT_COUNT = 101
 
+    ATR1_INDEX = 1
+    TXT2_INDEX = 2
+    TSY_INDEX = 3
+
     def __init__(
-        self,
-        info: LMS_FileInfo | None = None,
-        section_list: list[str] | None = None,
-        unsupported_section_map: dict[str, bytes] | None = None,
-        attribute_config: AttributeConfig | None = None,
-        tag_config: TagConfig | None = None,
+            self,
+            info: LMS_FileInfo | None = None,
+            section_list: list[str] | None = None,
+            unsupported_section_map: dict[str, bytes] | None = None,
+            attribute_config: AttributeConfig | None = None,
+            tag_config: TagConfig | None = None,
     ):
         self._info = info if info is not None else LMS_FileInfo()
 
@@ -54,14 +56,19 @@ class MSBT:
             encoding: FileEncoding = FileEncoding.UTF16,
             version: int = 3,
             section_count: int = 2):
-        """Creates a new MSBT instance.
+        """Create a new MSBT instance.
 
-        :param attribute_config: The attribute config object
-        :param tag_config: The tag config object
+        :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 encoding: the file encoding.
         :param version: the file version.
         :param section_count: the number of sections.
+
+        ========
+        Examples
+        ========
+        See https://github.com/AbdyyEee/PylibMS/wiki/MSBT#creating-a-msbt
         """
         return MSBT(info=LMS_FileInfo(is_big_endian, encoding, version, section_count),
                     attribute_config=attribute_config, tag_config=tag_config)
@@ -94,12 +101,12 @@ class MSBT:
 
     @property
     def has_attributes(self) -> bool:
-        """If the msbt contains attributes."""
+        """If the MSBT contains attributes."""
         return self.section_exists("ATR1")
 
     @property
-    def has_style_indexes(self) -> bool:
-        """If the msbt contains style indexes."""
+    def has_styles(self) -> bool:
+        """If the MSBT contains style indexes."""
         return self.section_exists("TSY1")
 
     def get_entry_by_index(self, index: int) -> MSBTEntry:
@@ -133,18 +140,23 @@ class MSBT:
         if entry.name in self._label_map:
             raise KeyError(f"The label '{entry.name}' already exists!")
 
+        # The implementation of ensuring section orders are maintained are done by constant indexes.
+        # In most MSBT files, it goes as LBL1 -> TXT2 -> ATR1 -> TSY1.
+        # If add_entry is utilized on a new MSBT instance, then these indexes ensure the order is maintained.
+        # While technically, undocumented sections (i.e. ATO1) can prefix TXT2 and other sections,
+        # we do not need to account for that scenario as they aren't supported by the library
+
         if self.section_exists("ATR1"):
             if entry.attribute is None:
                 raise ValueError(
                     f"Entry '{entry.name}' can't be added with no attributes when attributes already exist!"
                 )
         elif entry.attribute is not None:
-            self._section_list.insert(1, "ATR1")
+            self._section_list.insert(self.ATR1_INDEX, "ATR1")
             self._info.section_count += 1
 
-        # TXT2 will always exist so insert it at all times
         if not self.section_exists("TXT2"):
-            self._section_list.insert(2, "TXT2")
+            self._section_list.insert(self.TXT2_INDEX, "TXT2")
 
         if self.section_exists("TSY1"):
             if entry.style_index is None:
@@ -152,7 +164,7 @@ class MSBT:
                     f"Entry '{entry.name}' can't be added with no style index when styles already exist!"
                 )
         elif entry.style_index is not None:
-            self._section_list.insert(3, "TSY1")
+            self._section_list.insert(self.TSY_INDEX, "TSY1")
             self._info.section_count += 1
 
         self._entries.append(entry)
@@ -160,7 +172,7 @@ class MSBT:
 
     def delete_entry(self, entry: MSBTEntry) -> None:
         """
-        Removes an entry from the MSBT instance.
+        Deletes an entry from the MSBT instance.
 
         :param entry: the MSBTEntry object to remove.
         """
@@ -172,7 +184,7 @@ class MSBT:
 
     def section_exists(self, name: str) -> bool:
         """
-        Determines if a section exists in the current MSBT.
+        Determines if a section exists in the MSBT instance.
 
         :param name: the name of the section.
         """

{pylibms-3.2.6 → pylibms-3.3}/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
 
@@ -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-3.2.6 → pylibms-3.3}/lms/message/msbtio.py

@@ -9,6 +9,7 @@ from lms.message.msbt import MSBT
 from lms.message.msbtentry import MSBTEntry
 from lms.message.section.atr1 import (read_atr1, write_decoded_atr1,
                                       write_encoded_atr1)
+from lms.message.section.nli1 import read_nli1, write_nli1
 from lms.message.section.tsy1 import read_tsy1, write_tsy1
 from lms.message.section.txt2 import read_txt2, write_txt2
 from lms.titleconfig.config import AttributeConfig, TagConfig
@@ -17,11 +18,11 @@ __all__ = ["read_msbt", "read_msbt_path", "write_msbt", "write_msbt_path"]
 
 
 def read_msbt_path(
-    file_path: str,
-    *,
-    attribute_config: AttributeConfig | None = None,
-    tag_config: TagConfig | None = None,
-    suppress_tag_errors: bool = False,
+        file_path: str,
+        *,
+        attribute_config: AttributeConfig | None = None,
+        tag_config: TagConfig | None = None,
+        suppress_tag_errors: bool = False,
 ) -> MSBT:
     """
     Reads and retrieves a MSBT file from a given path.
@@ -31,8 +32,9 @@ def read_msbt_path(
     :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.
 
-    Example
-    ---------
+    =====
+    Usage
+    =====
     >>> msbt = read_msbt_path("path/to/file.msbt")
     """
     with open(file_path, "rb") as stream:
@@ -45,11 +47,11 @@ def read_msbt_path(
 
 
 def read_msbt(
-    stream: BinaryIO | bytes,
-    *,
-    attribute_config: AttributeConfig | None = None,
-    tag_config: TagConfig | None = None,
-    suppress_tag_errors: bool = False,
+        stream: BinaryIO | bytes,
+        *,
+        attribute_config: AttributeConfig | None = None,
+        tag_config: TagConfig | None = None,
+        suppress_tag_errors: bool = False,
 ) -> MSBT:
     """
     Reads and retrieves a MSBT file from a specified stream.
@@ -59,15 +61,19 @@ def read_msbt(
     :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.
 
-    Example
-    ---------
-    >>> msbt = read_msbt(stream)
+    =====
+    Usage
+    =====
+    >>> msbt = read_msbt_path("path/to/file.msbt")
     """
     reader = FileReader(stream)
     file_info = read_file_info(reader, MSBT.MAGIC)
 
     section_list = []
     unsupported_sections = {}
+
+    # While 101 is the default slot count for LBL1 sections in a MSBT
+    # The value may be overridden at the instance level... not sure why it varies though...
     slot_count = MSBT.DEFAULT_SLOT_COUNT
 
     messages = atr1_data = style_indexes = None
@@ -77,6 +83,8 @@ def read_msbt(
         match magic:
             case "LBL1":
                 labels, slot_count = read_labels(reader)
+            case "NLI1":
+                labels = read_nli1(reader)
             case "ATR1":
                 atr1_data = read_atr1(reader, attribute_config, size)
             case "TXT2":
@@ -112,13 +120,14 @@ def read_msbt(
 
 def write_msbt_path(file_path: str, file: MSBT) -> None:
     """
-    Writes a MSBT file to a given file path.
+    Writes a MSBT 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 MSBT file object.
 
-    Example
-    -------
+    =====
+    Usage
+    =====
     >>> write_msbt_path("path/to/file.msbt", msbt)
     """
     with open(file_path, "wb") as stream:
@@ -131,8 +140,9 @@ def write_msbt(file: MSBT) -> bytes:
 
     :param file: a MSBT object.
 
-    Example
-    -------
+    =====
+    Usage
+    =====
     >>> data = write_msbt(msbt)
     """
     if not isinstance(file, MSBT):
@@ -148,6 +158,9 @@ def write_msbt(file: MSBT) -> bytes:
             case "LBL1":
                 labels = [entry.name for entry in file]
                 write_section(writer, "LBL1", write_labels, labels, file.slot_count)
+            case "NLI1":
+                labels = [entry.name for entry in file]
+                write_section(writer, "NLI1", write_nli1, labels)
             case "ATR1":
                 attributes = [entry.attribute for entry in file]
                 if file.uses_encoded_attributes:

{pylibms-3.2.6 → pylibms-3.3}/lms/message/section/atr1.py

@@ -1,6 +1,5 @@
 from dataclasses import dataclass
 
-from lms.common.lms_datatype import LMS_DataType
 from lms.fileio.io import FileReader, FileWriter
 from lms.message.definitions.field.io import read_field, write_field
 from lms.message.definitions.field.lms_field import (LMS_DataType, LMS_Field,
@@ -16,7 +15,7 @@ class ATR1Data:
 
 
 def read_atr1(
-    reader: FileReader, config: AttributeConfig | None, section_size: int
+        reader: FileReader, config: AttributeConfig | None, section_size: int
 ) -> ATR1Data:
     if config is None:
         return read_encoded_atr1(reader, section_size)
@@ -72,11 +71,11 @@ def read_decoded_atr1(reader: FileReader, config: AttributeConfig) -> ATR1Data:
 
 
 def write_encoded_atr1(
-    writer: FileWriter,
-    attributes: list[bytes],
-    size_per_attribute: int,
-    string_table: bytes | None,
-):
+        writer: FileWriter,
+        attributes: list[bytes],
+        size_per_attribute: int,
+        string_table: bytes | None,
+) -> None:
     writer.write_uint32(len(attributes))
 
     if attributes:
@@ -92,7 +91,7 @@ def write_encoded_atr1(
 
 
 def write_decoded_atr1(
-    writer: FileWriter, attributes: list[LMS_FieldMap], size_per_attribute: int
+        writer: FileWriter, attributes: list[LMS_FieldMap], size_per_attribute: int
 ) -> None:
     writer.write_uint32(len(attributes))
     writer.write_uint32(size_per_attribute)

pylibms-3.3/lms/message/section/nli1.py

@@ -0,0 +1,22 @@
+from lms.fileio.io import FileReader, FileWriter
+
+
+def read_nli1(reader: FileReader) -> dict[int, str]:
+    entry_count = reader.read_uint32()
+
+    labels = {}
+    for _ in range(entry_count):
+        label = str(reader.read_uint32())
+        index = reader.read_uint32()
+        labels[index] = label
+
+    return labels
+
+
+def write_nli1(writer: FileWriter, labels: list[str]) -> None:
+    label_count = len(labels)
+    writer.write_uint32(label_count)
+
+    for i in range(label_count):
+        writer.write_uint32(int(labels[i]))
+        writer.write_uint32(i)

{pylibms-3.2.6 → pylibms-3.3}/lms/message/section/txt2.py

@@ -6,7 +6,7 @@ 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