legacy-puyo-tools 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

legacy_puyo_tools/__init__.py

@@ -1,7 +1,7 @@
 """A conversion tool for files used by the older Puyo games.
 
-Supports Puyo Puyo 7 and possibly Puyo Puyo! 15th Anniversary `mtx` and
-`fpd` files. Puyo Puyo!! 20th Anniversary is still not supported yet.
+Supports Puyo Puyo 7 and possibly Puyo Puyo! 15th Anniversary `mtx` and `fpd` files.
+Puyo Puyo!! 20th Anniversary is still not supported yet.
 
 SPDX-FileCopyrightText: 2025 Samuel Wu
 SPDX-License-Identifier: MIT

legacy_puyo_tools/__main__.py

@@ -0,0 +1,10 @@
+"""Allow the cli to be run from runpy or using `python -m legacy_puyo_tools`.
+
+SPDX-FileCopyrightText: 2025 Samuel Wu
+SPDX-License-Identifier: MIT
+"""
+
+if __name__ == "__main__":
+    from legacy_puyo_tools.cli import app
+
+    app()

legacy_puyo_tools/cli.py

@@ -4,6 +4,8 @@ SPDX-FileCopyrightText: 2025 Samuel Wu
 SPDX-License-Identifier: MIT
 """
 
+from __future__ import annotations
+
 from codecs import BOM_UTF16_LE
 from pathlib import Path
 from typing import BinaryIO
@@ -19,6 +21,7 @@ from legacy_puyo_tools.mtx import Mtx
 output_option = option(
     "--output",
     "-o",
+    "output_file",
     help="Output file. Defaults to an appropriate filename and extension.",
     type=cloup.File("wb"),
 )
@@ -44,11 +47,11 @@ mtx_options = option_group(
 
 @cloup.group()
 @cloup.version_option()
-def main() -> None:
+def app() -> None:
     """A conversion tool for files used by older Puyo games."""
 
 
-@main.group()
+@app.group()
 def create() -> None:
     """Create files to used by older Puyo games."""
 
@@ -60,21 +63,18 @@ def create() -> None:
     type=cloup.File("rb"),
 )
 @output_option
-def create_fpd(input_file: BinaryIO, output: BinaryIO | None) -> None:
-    """Create a fpd file from a unicode text file."""
+def create_fpd(input_file: BinaryIO, output_file: BinaryIO | None) -> None:
+    """Create a fpd file from a unicode text file."""  # noqa: DOC501
     if input_file.read(2) != BOM_UTF16_LE:
         raise FileFormatError(
             f"{input_file.name} is not a UTF-16 little-endian encoded text file."
         )
 
-    if output:
-        Fpd.read_unicode(input_file).write_fpd(output)
+    if output_file:
+        Fpd.read_unicode(input_file).write_fpd(output_file)
         return
 
-    path = Path(input_file.name).with_suffix("")
-
-    if path.suffix != ".fpd":
-        path = path.with_suffix(".fpd")
+    path = Path(input_file.name).with_suffix(".fpd")
 
     Fpd.read_unicode(input_file).write_fpd_to_path(path)
 
@@ -88,13 +88,13 @@ def create_fpd(input_file: BinaryIO, output: BinaryIO | None) -> None:
 @output_option
 @mtx_options
 def create_mtx(
-    input_file: BinaryIO, output: BinaryIO, fpd: Path | None, unicode: Path | None
+    input_file: BinaryIO, output_file: BinaryIO, fpd: Path | None, unicode: Path | None
 ) -> None:
     """Create a mtx file from a XML file."""
     raise NotImplementedError("Creating MTX files is currently not implemented yet.")
 
 
-@main.group()
+@app.group()
 def convert() -> None:
     """Convert files used by older Puyo games to an editable format."""
 
@@ -108,13 +108,10 @@ def convert_fpd(input_file: BinaryIO, output_file: BinaryIO | None) -> None:
     """Convert a fpd file to a UTF-16 little-endian unicode text file."""
     if output_file:
         output_file.write(BOM_UTF16_LE)
-        Fpd.read_fpd(input_file).write_fpd(output_file)
+        Fpd.read_fpd(input_file).write_unicode(output_file)
         return
 
-    path = Path(input_file.name).with_suffix("")
-
-    if path.suffix != ".fpd":
-        path = path.with_suffix(".fpd")
+    path = Path(input_file.name).with_suffix(".txt")
 
     Fpd.read_fpd(input_file).write_unicode_to_path(path)
 
@@ -127,11 +124,11 @@ def convert_fpd(input_file: BinaryIO, output_file: BinaryIO | None) -> None:
 @mtx_options
 def convert_mtx(
     input_file: BinaryIO,
-    output: BinaryIO | None,
+    output_file: BinaryIO | None,
     fpd: Path | None,
     unicode: Path | None,
 ) -> None:
-    """Convert a mtx file to a XML file."""
+    """Convert a mtx file to a XML file."""  # noqa: DOC501
     if fpd:
         fpd_data = Fpd.read_fpd_from_path(fpd)
     elif unicode:
@@ -141,17 +138,14 @@ def convert_mtx(
             "You must specify a character table using --fpd or --unicode."
         )
 
-    if output:
-        Mtx.read_mtx(input_file).write_xml(output, fpd_data)
+    if output_file:
+        Mtx.read_mtx(input_file).write_xml(output_file, fpd_data)
         return
 
-    path = Path(input_file.name).with_suffix("")
-
-    if path.suffix != ".xml":
-        path = path.with_suffix(".xml")
+    path = Path(input_file.name).with_suffix(".xml")
 
     Mtx.read_mtx(input_file).write_xml_to_file(path, fpd_data)
 
 
 if __name__ == "__main__":
-    main()
+    app()

legacy_puyo_tools/exceptions.py

@@ -1,5 +1,6 @@
 """Exceptions that might be thrown when parsing files.
 
+SPDX-FileCopyrightText: 2021 Nick Woronekin
 SPDX-FileCopyrightText: 2025 Samuel Wu
 SPDX-License-Identifier: MIT
 """

legacy_puyo_tools/fpd.py

@@ -7,12 +7,15 @@ SPDX-FileCopyrightText: 2025 Samuel Wu
 SPDX-License-Identifier: MIT
 """
 
+from __future__ import annotations
+
 from codecs import BOM_UTF16_LE
-from io import BytesIO
+from io import BytesIO, StringIO
+from os import PathLike
 from pathlib import Path
-from typing import BinaryIO, Self
+from typing import BinaryIO
 
-from attrs import define
+import attrs
 
 from legacy_puyo_tools.exceptions import FileFormatError, FormatError
 
@@ -22,7 +25,7 @@ UTF16_LENGTH = 2
 WIDTH_ENTRY_OFFSET = 2
 
 
-@define
+@attrs.define
 class FpdCharacter:
     """A fpd character entry.
 
@@ -53,16 +56,21 @@ class FpdCharacter:
         self.code_point = code_point.decode(ENCODING)
         self.width = width
 
+    def __str__(self) -> str:
+        """Returns the character as a single character string."""
+        return self.code_point
+
     def encode(self) -> bytes:
         """Encodes the character back to a fpd character entry.
 
         Returns:
             The character in UTF-16 LE format and its width.
         """
-        return self.code_point.encode(ENCODING) + self.width.to_bytes()
+        # TODO: When updating Python to 3.11, remove arguments from width.to_bytes
+        return self.code_point.encode(ENCODING) + self.width.to_bytes(1, "little")
 
     @classmethod
-    def decode(cls, fpd_entry: bytes) -> Self:
+    def decode(cls, fpd_entry: bytes) -> FpdCharacter:
         """Decodes a fpd character into its code point and width.
 
         Args:
@@ -82,7 +90,7 @@ class FpdCharacter:
         return cls(fpd_entry[:UTF16_LENGTH], fpd_entry[WIDTH_ENTRY_OFFSET])
 
 
-@define
+@attrs.define
 class Fpd:
     """A fpd character table.
 
@@ -110,8 +118,16 @@ class Fpd:
         """
         return self.entries[index].code_point
 
+    def __str__(self) -> str:
+        """Returns a string representation of the fpd character table."""
+        with StringIO() as string_buffer:
+            for character in self.entries:
+                string_buffer.write(str(character))
+
+            return string_buffer.getvalue()
+
     @classmethod
-    def read_fpd_from_path(cls, path: Path) -> Self:
+    def read_fpd_from_path(cls, path: str | PathLike[str]) -> Fpd:
         """Reads and extract characters from a fpd file.
 
         Args:
@@ -133,7 +149,7 @@ class Fpd:
                 raise FileFormatError(f"{path} is not a valid fpd file") from e
 
     @classmethod
-    def read_fpd(cls, fp: BinaryIO) -> Self:
+    def read_fpd(cls, fp: BinaryIO) -> Fpd:
         """Reads and extract characters from a file object.
 
         Args:
@@ -146,7 +162,7 @@ class Fpd:
         return cls.decode_fpd(fp.read())
 
     @classmethod
-    def decode_fpd(cls, data: bytes) -> Self:
+    def decode_fpd(cls, data: bytes) -> Fpd:
         """Extracts the fpd character table from a fpd encoded stream.
 
         Args:
@@ -161,7 +177,7 @@ class Fpd:
             for i in range(0, len(data), FPD_ENTRY_LENGTH)
         ])
 
-    def write_fpd_to_path(self, path: Path) -> None:
+    def write_fpd_to_path(self, path: str | PathLike[str]) -> None:
         """Writes the fpd character table to a fpd encoded file.
 
         Args:
@@ -193,7 +209,7 @@ class Fpd:
             return bytes_buffer.getvalue()
 
     @classmethod
-    def read_unicode_from_path(cls, path: Path) -> Self:
+    def read_unicode_from_path(cls, path: str | PathLike[str]) -> Fpd:
         """Reads and convert characters from a UTF-16 little-endian text file.
 
         Arguments:
@@ -218,7 +234,7 @@ class Fpd:
             return cls.read_unicode(fp)
 
     @classmethod
-    def read_unicode(cls, fp: BinaryIO) -> Self:
+    def read_unicode(cls, fp: BinaryIO) -> Fpd:
         """Reads and convert UTF-16 LE characters from a file object.
 
         Args:
@@ -232,7 +248,7 @@ class Fpd:
 
     # TODO: Somehow allow people to specify the width of the character during decoding
     @classmethod
-    def decode_unicode(cls, unicode: bytes) -> Self:
+    def decode_unicode(cls, unicode: bytes) -> Fpd:
         """Converts a UTF-16 LE stream into a fpd character table.
 
         Args:
@@ -247,7 +263,7 @@ class Fpd:
             for i in range(0, len(unicode), UTF16_LENGTH)
         ])
 
-    def write_unicode_to_path(self, path: Path) -> None:
+    def write_unicode_to_path(self, path: str | PathLike[str]) -> None:
         """Writes the fpd character table to a UTF-16 LE text file.
 
         Args:
@@ -275,8 +291,4 @@ class Fpd:
         Returns:
             A UTF-16 LE encoded text stream with characters from the fpd.
         """
-        with BytesIO() as bytes_buffer:
-            for character in self.entries:
-                bytes_buffer.write(character.code_point.encode(ENCODING))
-
-            return bytes_buffer.getvalue()
+        return str(self).encode(ENCODING)

legacy_puyo_tools/mtx.py

@@ -3,21 +3,44 @@
 This module converts mtx files to and from XML for modding Puyo games. Currently
 supports Puyo Puyo 7 and might support Puyo Puyo! 15th Anniversary.
 
+SPDX-FileCopyrightText: 2021 Nick Woronekin
 SPDX-FileCopyrightText: 2025 Samuel Wu
 SPDX-License-Identifier: MIT
 """
 
+from __future__ import annotations
+
+import sys
 from collections.abc import Callable
-from itertools import pairwise
+from os import PathLike
 from pathlib import Path
-from typing import BinaryIO, Literal, Self
+from typing import BinaryIO, Literal
 
-from attrs import define
+import attrs
 from lxml import etree
 
 from legacy_puyo_tools.exceptions import FileFormatError, FormatError
 from legacy_puyo_tools.fpd import Fpd
 
+# TODO: When updating to Python 3.10, remove the stub implementation of pairwise
+# from the python documentation:
+# https://docs.python.org/3/library/itertools.html#itertools.pairwise
+if sys.version_info >= (3, 10):
+    from itertools import pairwise
+else:
+    from collections.abc import Iterable
+    from itertools import tee
+    from typing import TypeVar
+
+    T = TypeVar("T")
+
+    def pairwise(iterable: Iterable[T]) -> Iterable[tuple[T, T]]:
+        """Simple pairwise implementation for Python < 3.10."""  # noqa: DOC201
+        a, b = tee(iterable)
+        next(b, None)
+        return zip(a, b)
+
+
 CHARACTER_WIDTH = 2
 ENDIAN = "little"
 
@@ -48,15 +71,16 @@ def _identify_mtx(data: bytes) -> tuple[Literal[8, 16], Literal[4, 8]]:
     raise FormatError("The given data is not in a valid `mtx` format")
 
 
-type MtxString = list[int]
+# TODO: When upgrading to Python 3.12, add type to the beginning of the alias
+MtxString = list[int]
 
 
-@define
+@attrs.define
 class Mtx:
     strings: list[MtxString]
 
     @classmethod
-    def read_mtx_from_file(cls, path: Path) -> Self:
+    def read_mtx_from_file(cls, path: str | PathLike[str]) -> Mtx:
         with Path(path).open("rb") as fp:
             try:
                 return cls.read_mtx(fp)
@@ -64,11 +88,11 @@ class Mtx:
                 raise FileFormatError(f"{path} is not a valid `mtx` file") from e
 
     @classmethod
-    def read_mtx(cls, fp: BinaryIO) -> Self:
+    def read_mtx(cls, fp: BinaryIO) -> Mtx:
         return cls.decode_mtx(fp.read())
 
     @classmethod
-    def decode_mtx(cls, data: bytes) -> Self:
+    def decode_mtx(cls, data: bytes) -> Mtx:
         length = int.from_bytes(data[:4], ENDIAN)
 
         if length != len(data):
@@ -98,7 +122,7 @@ class Mtx:
 
         return cls(strings)
 
-    def write_xml_to_file(self, path: Path, fpd: Fpd) -> None:
+    def write_xml_to_file(self, path: str | PathLike[str], fpd: Fpd) -> None:
         with Path(path).open("wb") as fp:
             self.write_xml(fp, fpd)
 
@@ -114,18 +138,18 @@ class Mtx:
             dialog.text = "\n"
 
             for character in string:
-                match character:
-                    case 0xF813:
-                        dialog.append(etree.Element("arrow"))
-                    # TODO: Figure out what this control character does
-                    case 0xF883:
-                        dialog.text += "0xF883"
-                    case 0xFFFD:
-                        dialog.text += "\n"
-                    case 0xFFFF:
-                        break
-                    case _:
-                        dialog.text += fpd[character]
+                # TODO: When upgrading to Python 3.10, use `match` statements
+                if character == 0xF813:
+                    dialog.append(etree.Element("arrow"))
+                # TODO: Figure out what this control character does
+                elif character == 0xF883:
+                    dialog.text += "0xF883"
+                elif character == 0xFFFD:
+                    dialog.text += "\n"
+                elif character == 0xFFFF:
+                    break
+                else:
+                    dialog.text += fpd[character]
 
         etree.indent(root)
 

{legacy_puyo_tools-0.1.0.dist-info → legacy_puyo_tools-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: legacy-puyo-tools
-Version: 0.1.0
+Version: 0.2.0
 Summary: A tool to edit text for older Puyo Puyo games.
 Project-URL: changelog, https://github.com/wushenrong/legacy-puyo-tools/blob/main/CHANGELOG.md
 Project-URL: homepage, https://github.com/wushenrong/legacy-puyo-tools
@@ -14,26 +14,32 @@ Classifier: Development Status :: 2 - Pre-Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Other Audience
 Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: File Formats
 Classifier: Topic :: Games/Entertainment :: Puzzle Games
 Classifier: Topic :: Utilities
-Requires-Python: >=3.13
+Requires-Python: >=3.9
 Requires-Dist: attrs>=25.3.0
-Requires-Dist: click>=8.2.1
+Requires-Dist: click>=8.1.8
 Requires-Dist: cloup>=3.0.7
 Requires-Dist: lxml>=6.0.0
 Description-Content-Type: text/markdown
 
 # Legacy Puyo Tools
 
-A command line tool for modding older Puyo Puyo games. (Yes, the name is using a
-[reversed naming scheme](https://github.com/microsoft/WSL).)
+A command line tool for modding older Puyo Puyo games (Yes, the name is using a
+[reversed naming scheme](https://github.com/microsoft/WSL)).
 
 ## Installation
 
-Install the latest version [Python](https://www.python.org/).
+Install [Python](https://www.python.org/) 3.9 or later, preferably the latest
+version.
 
 `legacy-python-tools` is published to
 [PyPI](https://pypi.org/project/legacy-puyo-tools/). It is recommended to
@@ -62,14 +68,10 @@ And of course, you can use good old pip in a virtual Python environment using
 
 ```bash
 # Create a virtual python environment
-virualenv .venv
-# Or with the venv library
 python -m venv .venv
 # Activate the virtual environment
 ./.venv/Scripts/activate
 # Install legacy-python-tools
-pip install legacy-python-tools
-# Or using the pip module
 python -m pip install legacy-python-tools
 ```
 
@@ -98,21 +100,28 @@ This tool will try to support formats from the following Puyo games:
 - Puyo Puyo 7
 - Puyo Puyo!! 20th Annversivery (If there is demand)
 
-See [Formats](formats.md) for detailed information about those formats, and the
-current progress on creating and converting them.
+See
+[Formats](https://github.com/wushenrong/legacy-puyo-tools/blob/main/formats.md)
+for detailed information about these formats, and the current progress on
+creating and converting them.
 
 ## Why
 
 The [Puyo Text Editor][puyo-text-editor] can already do what `legacy-puyo-tools`
-does and is the inspiration of this tool, but there are advantages to rewriting
-it in Python:
+does and is the inspiration of this tool, but there are advantages to rewrite it
+in Python:
 
 [puyo-text-editor]: https://github.com/nickworonekin/puyo-text-editor
 
 - Better cross compatibility with Linux.
-- Don't have to update the language version every time it becomes End of Life.
+- Easier migration when upgrade away from end of life language versions.
 - Avoids the rigidness of using a pure object-oriented design.
 
+## Contributing
+
+If you want to contribute to the project check out
+[Contributing](https://github.com/wushenrong/legacy-puyo-tools/blob/main/CONTRIBUTING.md).
+
 ## License
 
 Under the MIT License. Based on [Puyo Text Editor][puyo-text-editor] which is

legacy_puyo_tools-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+legacy_puyo_tools/__init__.py,sha256=LjS0jFv5pdhJceptQG9WtToZKBMzwCCXRiCa9YofnO0,277
+legacy_puyo_tools/__main__.py,sha256=LCp7zRagZzAyqpsJSzgMlRF36sWvMMNC7Ufq52cUdVQ,232
+legacy_puyo_tools/cli.py,sha256=ql8nEAiojQTpl1ug6VMYIaWEXHko2_JJHk8_w7ZhCac,4128
+legacy_puyo_tools/exceptions.py,sha256=0xT7q1t1r_YSZAv7OUPUgiui1QN3AwBw4cNyxOt_pkA,472
+legacy_puyo_tools/fpd.py,sha256=2_FBRSZjmioYYbZ7govMqtEkXdh1Exl3NmfswvZQ1qY,8763
+legacy_puyo_tools/mtx.py,sha256=3DukplefdG7jnsLaDXoQ68QaUto9qpsmYgMPmF0Pksk,4972
+legacy_puyo_tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+legacy_puyo_tools-0.2.0.dist-info/METADATA,sha256=PqX1AU9Jr4lkZ6ynmTWFLlt1qVP0b1wCJEn-oohLMXY,4042
+legacy_puyo_tools-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+legacy_puyo_tools-0.2.0.dist-info/entry_points.txt,sha256=U1UoBDFd576Xi_8PuLVUXZcGV6Idk1Bc-UlF9UNYYh0,64
+legacy_puyo_tools-0.2.0.dist-info/licenses/LICENSE,sha256=4G2c45JIaRJFR-0AbNA1uV354akZGEcbnBgpdNokvGE,1117
+legacy_puyo_tools-0.2.0.dist-info/RECORD,,

legacy_puyo_tools-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+legacy-puyo-tools = legacy_puyo_tools.cli:app

{legacy_puyo_tools-0.1.0.dist-info → legacy_puyo_tools-0.2.0.dist-info}/licenses/LICENSE

@@ -1,5 +1,6 @@
 MIT License
 
+Copyright (c) 2021 Nick Woronekin
 Copyright (c) 2025 Samuel Wu and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of

legacy_puyo_tools-0.1.0.dist-info/RECORD

@@ -1,11 +0,0 @@
-legacy_puyo_tools/__init__.py,sha256=tTzyNju0CFsXWki9ttjO6qnNx4Dlmur-1zgJ-n9toB0,277
-legacy_puyo_tools/cli.py,sha256=qYBGmjO2LU5afTcwcGw3WJK-csDbaJF9lr_7mxlDkeA,4207
-legacy_puyo_tools/exceptions.py,sha256=o0iH8s9qtt6ra8qaRW470amMszwUofsOMJr0mkCnVjM,428
-legacy_puyo_tools/fpd.py,sha256=7pWdfREmNFRiIMsncwUF4h5yFV3TkIPenEagfx_8Hxc,8287
-legacy_puyo_tools/mtx.py,sha256=fIRQJzx3UXv5q95k05eH99Ouh56CwpNRfP5uiI5S91k,4145
-legacy_puyo_tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-legacy_puyo_tools-0.1.0.dist-info/METADATA,sha256=j1yyrc2f-lA-IJCv9EPUlbTPVy7DGqKmzoMnLXO-bwE,3660
-legacy_puyo_tools-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-legacy_puyo_tools-0.1.0.dist-info/entry_points.txt,sha256=SWkgMVVrmWMKaFJXbb0vx-qAjqMWnxm3_0AVwYCdZLs,65
-legacy_puyo_tools-0.1.0.dist-info/licenses/LICENSE,sha256=C-K9I-yQXfd_K7nB9-9HgmhXprEcMcObZsRTv02ZWP8,1083
-legacy_puyo_tools-0.1.0.dist-info/RECORD,,

legacy_puyo_tools-0.1.0.dist-info/entry_points.txt

@@ -1,2 +0,0 @@
-[console_scripts]
-legacy-puyo-tools = legacy_puyo_tools.cli:main