legacy-puyo-tools 0.0.1__tar.gz → 0.1.0__tar.gz

{legacy_puyo_tools-0.0.1 → legacy_puyo_tools-0.1.0}/.github/workflows/ci.yaml

@@ -20,9 +20,12 @@ jobs:
       - uses: actions/checkout@v4
       - uses: astral-sh/setup-uv@v6
       - uses: actions/setup-python@v5
+        with:
+          python-version-file: "pyproject.toml"
 
-      # Disable rules about documentation and TODOs in CI
-      # Let the developer decide when to fix them
+      # Disable rules about documentation and TODOs in CI.
+      # Instead yell at the developer and let them decide when to add
+      # documentation or remove TODOs.
       - name: Ruff lint
         run: uv run ruff check --fix --ignore=D101,D102,FIX002
       - name: Lint using pylint

{legacy_puyo_tools-0.0.1 → legacy_puyo_tools-0.1.0}/.github/workflows/release.yaml

@@ -17,21 +17,13 @@ jobs:
     permissions:
       id-token: write
     steps:
+      # Setup environment
       - uses: actions/checkout@v4
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v6
-        with:
-          enable-cache: true
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-python@v5
         with:
           python-version-file: "pyproject.toml"
 
-      - name: Install package
-        run: uv sync --locked --all-extras --dev
-
       - name: Build package
         run: uv build
 

{legacy_puyo_tools-0.0.1 → legacy_puyo_tools-0.1.0}/.markdownlint.yaml

@@ -59,4 +59,4 @@ link-image-style:
   url_inline: false
 
 table-pipe-style:
-  style: no_leading_or_trailing
+  style: leading_and_trailing

{legacy_puyo_tools-0.0.1 → legacy_puyo_tools-0.1.0}/CHANGELOG.md

@@ -6,6 +6,20 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.1.0 - 2025-07-16
+
+### Added
+
+- Installation, usage, and supported games sections in README.md.
+- Information about the `fmp` format (#2).
+
+### Changed
+
+- Rewrite the command line interface to use [`cloup`] instead of `argparse`.
+- Update formats.md with current support progress.
+
+[`cloup`]: https://cloup.readthedocs.io
+
 ## 0.0.1 - 2025-07-15
 
 ### Added

legacy_puyo_tools-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,128 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+-   Demonstrating empathy and kindness toward other people
+-   Being respectful of differing opinions, viewpoints, and experiences
+-   Giving and gracefully accepting constructive feedback
+-   Accepting responsibility and apologizing to those affected by our mistakes,
+    and learning from the experience
+-   Focusing on what is best not just for us as individuals, but for the
+    overall community
+
+Examples of unacceptable behavior include:
+
+-   The use of sexualized language or imagery, and sexual attention or
+    advances of any kind
+-   Trolling, insulting or derogatory comments, and personal or political attacks
+-   Public or private harassment
+-   Publishing others' private information, such as a physical or email
+    address, without their explicit permission
+-   Other conduct which could reasonably be considered inappropriate in a
+    professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+<twopizza9621536@gmail.com>.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series
+of actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.0, available at
+<https://www.contributor-covenant.org/version/2/0/code_of_conduct.html>.
+
+Community Impact Guidelines were inspired by [Mozilla's code of conduct
+enforcement ladder](https://github.com/mozilla/diversity).
+
+[homepage]: https://www.contributor-covenant.org
+
+For answers to common questions about this code of conduct, see the FAQ at
+<https://www.contributor-covenant.org/faq>. Translations are available at
+<https://www.contributor-covenant.org/translations>.

legacy_puyo_tools-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# How to contribute
+
+Want a feature to be added to `legacy-puyo-tools` or found a bug that needs to
+be fixed. Great! Create an issue at
+<https://github.com/wushenrong/legacy-puyo-tools/issues> and add a description
+on why a feature should be added or how the bug occurred.
+
+If you are contributing code, be sure to add a signoff to your commits with the
+`-s` or `--signoff` flag as this project uses the
+[Developer Certificate of Origin][dco] to resolve licensing issues between
+contributors.
+
+[dco]: https://developercertificate.org/
+
+Do not forget to read and follow the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Contributors
+
+- @52871299hzy for contributing information about the `fmp` format.
+
+## Developer Certificate of Origin
+
+Below is a reproduction of the [DCO][dco] for reference.
+
+```txt
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.
+```

{legacy_puyo_tools-0.0.1 → legacy_puyo_tools-0.1.0}/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Samuel Wu
+Copyright (c) 2025 Samuel Wu and contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

legacy_puyo_tools-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: legacy-puyo-tools
+Version: 0.1.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
+Project-URL: issues, https://github.com/wushenrong/legacy-puyo-tools/issues
+Project-URL: source, https://github.com/wushenrong/legacy-puyo-tools.git
+Author-email: Samuel Wu <twopizza9621536@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: puyopuyo
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Other Audience
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: File Formats
+Classifier: Topic :: Games/Entertainment :: Puzzle Games
+Classifier: Topic :: Utilities
+Requires-Python: >=3.13
+Requires-Dist: attrs>=25.3.0
+Requires-Dist: click>=8.2.1
+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).)
+
+## Installation
+
+Install the latest version [Python](https://www.python.org/).
+
+`legacy-python-tools` is published to
+[PyPI](https://pypi.org/project/legacy-puyo-tools/). It is recommended to
+install tools from PyPI into an isolated Python environment.
+
+You can use [`pipx`](https://pipx.pypa.io):
+
+```bash
+pipx install legacy-python-tools
+# Or to run the cli without installing legacy-python-tools
+pipx run legacy-python-tools
+```
+
+Or [`uv`](https://docs.astral.sh/uv):
+
+```bash
+uv tool install legacy-python-tools
+# Or to run the cli without installing legacy-python-tools
+uv tool run legacy-python-tools
+# Or the shorter uvx
+uvx legacy-python-tools
+```
+
+And of course, you can use good old pip in a virtual Python environment using
+[`virualenv`](https://virtualenv.pypa.io) or the built-in `venv` library:
+
+```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
+```
+
+## Usage
+
+Create a `fpd` file from a UTF-16 little-endian encoded text file.
+
+```bash
+legacy-puyo-tools create fpd puyo14.txt
+```
+
+Or convert a `mtx` file to an editable XML file using a `fpd` file.
+
+```bash
+legacy-puyo-tools convert mtx --output custom_als.mtx --fpd puyo14.fpd als.xml
+```
+
+You can use the `--help` flag to see what sub-commands and options are
+available.
+
+## Supported Games
+
+This tool will try to support formats from the following Puyo games:
+
+- Puyo Puyo! 15th Annversivery
+- 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.
+
+## 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:
+
+[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.
+- Avoids the rigidness of using a pure object-oriented design.
+
+## License
+
+Under the MIT License. Based on [Puyo Text Editor][puyo-text-editor] which is
+also under the MIT License.

legacy_puyo_tools-0.1.0/README.md

@@ -0,0 +1,91 @@
+# 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).)
+
+## Installation
+
+Install the latest version [Python](https://www.python.org/).
+
+`legacy-python-tools` is published to
+[PyPI](https://pypi.org/project/legacy-puyo-tools/). It is recommended to
+install tools from PyPI into an isolated Python environment.
+
+You can use [`pipx`](https://pipx.pypa.io):
+
+```bash
+pipx install legacy-python-tools
+# Or to run the cli without installing legacy-python-tools
+pipx run legacy-python-tools
+```
+
+Or [`uv`](https://docs.astral.sh/uv):
+
+```bash
+uv tool install legacy-python-tools
+# Or to run the cli without installing legacy-python-tools
+uv tool run legacy-python-tools
+# Or the shorter uvx
+uvx legacy-python-tools
+```
+
+And of course, you can use good old pip in a virtual Python environment using
+[`virualenv`](https://virtualenv.pypa.io) or the built-in `venv` library:
+
+```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
+```
+
+## Usage
+
+Create a `fpd` file from a UTF-16 little-endian encoded text file.
+
+```bash
+legacy-puyo-tools create fpd puyo14.txt
+```
+
+Or convert a `mtx` file to an editable XML file using a `fpd` file.
+
+```bash
+legacy-puyo-tools convert mtx --output custom_als.mtx --fpd puyo14.fpd als.xml
+```
+
+You can use the `--help` flag to see what sub-commands and options are
+available.
+
+## Supported Games
+
+This tool will try to support formats from the following Puyo games:
+
+- Puyo Puyo! 15th Annversivery
+- 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.
+
+## 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:
+
+[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.
+- Avoids the rigidness of using a pure object-oriented design.
+
+## License
+
+Under the MIT License. Based on [Puyo Text Editor][puyo-text-editor] which is
+also under the MIT License.

legacy_puyo_tools-0.1.0/REUSE.toml

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2025 Samuel Wu
+#
+# SPDX-License-Identifier: MIT-0
+
+version = 1
+
+[[annotations]]
+SPDX-FileCopyrightText = "2025 Samuel Wu and contributors"
+SPDX-License-Identifier = "MIT"
+path = ["formats.md"]
+
+[[annotations]]
+SPDX-FileCopyrightText = "2025 Samuel Wu"
+SPDX-License-Identifier = "MIT-0"
+path = ["CHANGELOG.md", "CONTRIBUTING.md", "README.md", "uv.lock"]
+
+[[annotations]]
+SPDX-FileCopyrightText = "2014 Coraline Ada Ehmke"
+SPDX-License-Identifier = "CC-BY-4.0"
+path = ["CODE_OF_CONDUCT.md"]

legacy_puyo_tools-0.1.0/formats.md

@@ -0,0 +1,49 @@
+# Formats
+
+Below are the formats that are used by the older Puyo games. This includes how
+each format is structured and the current progress on creating and converting
+them.
+
+## The `fpd` format
+
+Both the creation and conversion of `fpd` are fully implemented.
+
+The `fpd` format is a binary character table format used by the developers of
+Puyo Puyo! 15th Anniversary and Puyo Puyo 7 to convert characters from UTF-16
+little-endian into an index that can be used by the `mtx` for text. Each
+character entry in the `fpd` is 3 bytes long and formatted as follows:
+`XX XX YY`. Where `XX XX` is the character encoded in UTF-16 little-endian and
+`YY` is the width of the character. The entries are placed next to each other,
+creating a zero-based index that is offset by multiples of `0x03`. I.e. the 1st
+character is at index `0x00`, the 2nd character is at index `0x03`, the 3rd
+character is at index `0x06`, etc.
+
+The `fpd` is not used by the games internally except for the Nintendo DS version
+of the games.
+
+## The `fmp` format
+
+The `fmp` format is a bitmap format used by the Nintendo DS versions of Puyo
+Puyo! 15th Anniversary and Puyo Puyo 7 to store the pixel data of the font
+corresponding to the `fpd` file. Characters are stored in the same order as the
+`fpd` file. Each character is either 14x14 pixels (in `puyo14.fmp` and
+`test.fmp`) or 8x8 pixels (in `puyo8.fmp`). The image data is stored in a packed
+format where each byte encodes two horizontal pixels, where the lower nibble
+(4 bits) represent the left pixel and the higher nibble represent the right
+one:
+
+- `0x1` represents a visible pixel (on pixel)
+- `0x0` represents an empty pixel (off pixel)
+
+Pixels are stored row by row, in top-to-bottom and left-to-right order. There
+are no headers or padding bytes in the file.
+
+## The `mtx` format
+
+The creation of `mtx` has not been implemented yet while conversion only has
+partial support.
+
+<!-- TODO: Finish the mtx format for PP15 and PP7 -->
+<!-- TODO: Look at the mtx format for PP20 -->
+The `mtx` format is a binary-encoded format used by older Puyo games for
+storing character dialog and text.

{legacy_puyo_tools-0.0.1 → legacy_puyo_tools-0.1.0}/pyproject.toml

@@ -4,20 +4,41 @@
 
 [project]
 authors = [{ name = "Samuel Wu", email = "twopizza9621536@gmail.com" }]
-dependencies = ["attrs>=25.3.0", "lxml>=6.0.0"]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Environment :: Console",
+    "License :: OSI Approved :: MIT License",
+
+    # Intended Audience
+    "Intended Audience :: Other Audience",
+    "Topic :: File Formats",
+    "Topic :: Games/Entertainment :: Puzzle Games",
+    "Topic :: Utilities",
+
+    # Python Versions
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = ["attrs>=25.3.0", "click>=8.2.1", "cloup>=3.0.7", "lxml>=6.0.0"]
 description = "A tool to edit text for older Puyo Puyo games."
+keywords = ["puyopuyo"]
 license = "MIT"
 license-files = ["LICENSE"]
 name = "legacy-puyo-tools"
 readme = "README.md"
 requires-python = ">=3.13"
-version = "0.0.1"
+version = "0.1.0"
+
+[project.urls]
+changelog = "https://github.com/wushenrong/legacy-puyo-tools/blob/main/CHANGELOG.md"
+homepage = "https://github.com/wushenrong/legacy-puyo-tools"
+issues = "https://github.com/wushenrong/legacy-puyo-tools/issues"
+source = "https://github.com/wushenrong/legacy-puyo-tools.git"
 
 [project.scripts]
 legacy-puyo-tools = "legacy_puyo_tools.cli:main"
 
 [tool.ruff]
-line-length = 79
 output-format = "concise"
 # Required for some rules
 preview = true
@@ -56,17 +77,16 @@ typing-modules = ["types-lxml"]
 # Disable rules that conflict with the formatter
 ignore = ["COM812"]
 
-[tool.ruff.lint.pycodestyle]
-max-doc-length = 72
+[tool.ruff.lint.per-file-ignores]
+"src/legacy_puyo_tools/cli.py" = ["DOC501"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"
 
 [tool.pylint]
 extension-pkg-allow-list = ["lxml"]
-max-line-length = 79
+max-line-length = 88
 output-format = "colorized"
-source-roots = ["src"]
 
 [tool.pyright]
 include = ["src"]

legacy_puyo_tools-0.1.0/src/legacy_puyo_tools/cli.py

@@ -0,0 +1,157 @@
+"""A commandline interface for the conversion tools.
+
+SPDX-FileCopyrightText: 2025 Samuel Wu
+SPDX-License-Identifier: MIT
+"""
+
+from codecs import BOM_UTF16_LE
+from pathlib import Path
+from typing import BinaryIO
+
+import cloup
+from cloup import option, option_group
+from cloup.constraints import require_one
+
+from legacy_puyo_tools.exceptions import ArgumentError, FileFormatError
+from legacy_puyo_tools.fpd import Fpd
+from legacy_puyo_tools.mtx import Mtx
+
+output_option = option(
+    "--output",
+    "-o",
+    help="Output file. Defaults to an appropriate filename and extension.",
+    type=cloup.File("wb"),
+)
+
+mtx_options = option_group(
+    "Character table options",
+    option(
+        "--fpd",
+        help="Use a fpd file as the character table.",
+        type=cloup.Path(exists=True, dir_okay=False, path_type=Path),
+    ),
+    option(
+        "--unicode",
+        help="Use a unicode text file as the character table.",
+        type=cloup.Path(exists=True, dir_okay=False, path_type=Path),
+    ),
+    constraint=require_one.rephrased(
+        "exactly 1 character table required for mtx files",
+        "exactly 1 character table must be specified",
+    ),
+)
+
+
+@cloup.group()
+@cloup.version_option()
+def main() -> None:
+    """A conversion tool for files used by older Puyo games."""
+
+
+@main.group()
+def create() -> None:
+    """Create files to used by older Puyo games."""
+
+
+@create.command(name="fpd")
+@cloup.argument(
+    "input_file",
+    help="Unicode text file encoded in UTF-16 little-endian.",
+    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."""
+    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)
+        return
+
+    path = Path(input_file.name).with_suffix("")
+
+    if path.suffix != ".fpd":
+        path = path.with_suffix(".fpd")
+
+    Fpd.read_unicode(input_file).write_fpd_to_path(path)
+
+
+@create.command(name="mtx", show_constraints=True)
+@cloup.argument(
+    "input_file",
+    help="XML file that contains markup text or dialog.",
+    type=cloup.File("rb"),
+)
+@output_option
+@mtx_options
+def create_mtx(
+    input_file: BinaryIO, output: 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()
+def convert() -> None:
+    """Convert files used by older Puyo games to an editable format."""
+
+
+@convert.command(name="fpd")
+@cloup.argument(
+    "input_file", help="Fpd file containing character data.", type=cloup.File("rb")
+)
+@output_option
+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)
+        return
+
+    path = Path(input_file.name).with_suffix("")
+
+    if path.suffix != ".fpd":
+        path = path.with_suffix(".fpd")
+
+    Fpd.read_fpd(input_file).write_unicode_to_path(path)
+
+
+@convert.command(name="mtx", show_constraints=True)
+@cloup.argument(
+    "input_file", help="Mtx file containing Manzai text.", type=cloup.File("rb")
+)
+@output_option
+@mtx_options
+def convert_mtx(
+    input_file: BinaryIO,
+    output: BinaryIO | None,
+    fpd: Path | None,
+    unicode: Path | None,
+) -> None:
+    """Convert a mtx file to a XML file."""
+    if fpd:
+        fpd_data = Fpd.read_fpd_from_path(fpd)
+    elif unicode:
+        fpd_data = Fpd.read_unicode_from_path(unicode)
+    else:
+        raise ArgumentError(
+            "You must specify a character table using --fpd or --unicode."
+        )
+
+    if output:
+        Mtx.read_mtx(input_file).write_xml(output, fpd_data)
+        return
+
+    path = Path(input_file.name).with_suffix("")
+
+    if path.suffix != ".xml":
+        path = path.with_suffix(".xml")
+
+    Mtx.read_mtx(input_file).write_xml_to_file(path, fpd_data)
+
+
+if __name__ == "__main__":
+    main()

{legacy_puyo_tools-0.0.1 → legacy_puyo_tools-0.1.0}/src/legacy_puyo_tools/exceptions.py

@@ -11,3 +11,7 @@ class FormatError(Exception):
 
 class FileFormatError(FormatError):
     """The file does not conform to a file format or is malformed."""
+
+
+class ArgumentError(Exception):
+    """One of the argument is invalid or missing."""

{legacy_puyo_tools-0.0.1 → legacy_puyo_tools-0.1.0}/src/legacy_puyo_tools/fpd.py

@@ -1,7 +1,7 @@
-"""fpd conversion tool for older puyo games.
+"""Fpd conversion tool for older Puyo games.
 
-This module supports the encoding and decoding of the fpd format used by
-Puyo Puyo! 15th Anniversary and Puyo Puyo 7.
+This module supports the encoding and decoding of the fpd format used by Puyo Puyo! 15th
+Anniversary and Puyo Puyo 7.
 
 SPDX-FileCopyrightText: 2025 Samuel Wu
 SPDX-License-Identifier: MIT
@@ -26,16 +26,16 @@ WIDTH_ENTRY_OFFSET = 2
 class FpdCharacter:
     """A fpd character entry.
 
-    A fpd character is a binary entry that is 3 bytes long and formatted
-    as follows: `XX XX YY`. Where `XX XX` is the character encoded in
-    UTF-16 LE and `YY` is the width of the character.
+    A fpd character is a binary entry that is 3 bytes long and formatted as follows:
+    `XX XX YY`. Where `XX XX` is the character encoded in UTF-16 little-endian and `YY`
+    is the width of the character.
 
     Attributes:
         code_point:
             A string that stores a single character.
         width:
-            How wide should the character be, only used in the Nintendo
-            DS versions of the games.
+            How wide should the character be, only used in the Nintendo DS versions of
+            the games.
     """
 
     code_point: str
@@ -71,16 +71,13 @@ class FpdCharacter:
 
         Raises:
             FormatError:
-                The entry given does not conform to the fpd character
-                format.
+                The entry given does not conform to the fpd character format.
 
         Returns:
             A fpd character entry containing its code point and width.
         """
         if len(fpd_entry) != FPD_ENTRY_LENGTH:
-            raise FormatError(
-                f"{fpd_entry} does not matches size {FPD_ENTRY_LENGTH}"
-            )
+            raise FormatError(f"{fpd_entry} does not matches size {FPD_ENTRY_LENGTH}")
 
         return cls(fpd_entry[:UTF16_LENGTH], fpd_entry[WIDTH_ENTRY_OFFSET])
 
@@ -89,10 +86,10 @@ class FpdCharacter:
 class Fpd:
     """A fpd character table.
 
-    The fpd stores character table in which each entry is placed right
-    next to each other and the indices is offset by multiples of `0x03`.
-    I.e. The 1st character is at index `0x00`, the 2nd character is at
-    index `0x03`, the 3rd character is at index `0x06`, etc.
+    The fpd stores character table in which each entry is placed right next to each
+    other and the indices is offset by multiples of `0x03`. I.e. The 1st character is at
+    index `0x00`, the 2nd character is at index `0x03`, the 3rd character is at index
+    `0x06`, etc.
 
     Attributes:
         entries:
@@ -119,13 +116,12 @@ class Fpd:
 
         Args:
             path:
-                A path to a fpd encoded file that contains a fpd
-                character table.
+                A path to a fpd encoded file that contains a fpd character table.
 
         Raises:
             FileFormatError:
-                The fpd file contain a entry that does not conform
-                to the fpd character format.
+                The fpd file contain a entry that does not conform to the fpd character
+                format.
 
         Returns:
             A fpd character table.
@@ -155,8 +151,7 @@ class Fpd:
 
         Args:
             data:
-                A fpd encoded stream that contains a fpd character
-                table.
+                A fpd encoded stream that contains a fpd character table.
 
         Returns:
             A fpd character table.
@@ -199,25 +194,26 @@ class Fpd:
 
     @classmethod
     def read_unicode_from_path(cls, path: Path) -> Self:
-        """Reads and convert characters from a UTF-16 LE text file.
+        """Reads and convert characters from a UTF-16 little-endian text file.
 
         Arguments:
-            path:
-                A path to a UTF-16 LE text file.
+            path: A path to a UTF-16 LE text file.
 
         Raises:
             FileFormatError:
-                The file is not a UTF-16 LE encoded text file or is
-                missing the Byte Order Mark for UTF-16 LE.
+                The file is not a UTF-16 little-endian encoded text file or is missing
+                the Byte Order Mark for UTF-16 little-endian.
 
         Returns:
             A fpd character table.
         """
         with Path(path).open("rb") as fp:
-            # Check the Byte Order Mark (BOM) to see if it is really a
-            # UTF-16 LE text file
+            # Check the Byte Order Mark (BOM) to see if it is really a UTF-16 LE text
+            # file
             if fp.read(2) != BOM_UTF16_LE:
-                raise FileFormatError(f"{path} is not a UTF-16 LE text file.")
+                raise FileFormatError(
+                    f"{path} is not a UTF-16 little-endian text file."
+                )
 
             return cls.read_unicode(fp)
 
@@ -234,8 +230,7 @@ class Fpd:
         """
         return cls.decode_unicode(fp.read())
 
-    # TODO: Somehow allow people to specify the width of the character
-    # during decoding
+    # TODO: Somehow allow people to specify the width of the character during decoding
     @classmethod
     def decode_unicode(cls, unicode: bytes) -> Self:
         """Converts a UTF-16 LE stream into a fpd character table.
@@ -278,8 +273,7 @@ class Fpd:
         """Encodes the fpd character table into a UTF-16 LE text stream.
 
         Returns:
-            A UTF-16 LE encoded text stream with characters from the
-            fpd.
+            A UTF-16 LE encoded text stream with characters from the fpd.
         """
         with BytesIO() as bytes_buffer:
             for character in self.entries:

{legacy_puyo_tools-0.0.1 → legacy_puyo_tools-0.1.0}/src/legacy_puyo_tools/mtx.py

@@ -1,8 +1,7 @@
 """Manzai text conversion tool for older Puyo Puyo games.
 
-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.
+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: 2025 Samuel Wu
 SPDX-License-Identifier: MIT
@@ -62,9 +61,7 @@ class Mtx:
             try:
                 return cls.read_mtx(fp)
             except FormatError as e:
-                raise FileFormatError(
-                    f"{path} is not a valid `mtx` file"
-                ) from e
+                raise FileFormatError(f"{path} is not a valid `mtx` file") from e
 
     @classmethod
     def read_mtx(cls, fp: BinaryIO) -> Self:
@@ -85,9 +82,7 @@ class Mtx:
 
         sections = [
             read_offset(data, section_table_offset + (i * int_width))
-            for i in range(
-                (string_table_offset - section_table_offset) // int_width
-            )
+            for i in range((string_table_offset - section_table_offset) // int_width)
         ]
 
         # Add the length to the sections so we can read to end of stream
@@ -97,9 +92,7 @@ class Mtx:
 
         for current_string_offset, next_string_offset in pairwise(sections):
             strings.append([
-                _read_character(
-                    data, current_string_offset + (i * CHARACTER_WIDTH)
-                )
+                _read_character(data, current_string_offset + (i * CHARACTER_WIDTH))
                 for i in range(next_string_offset - current_string_offset)
             ])
 

{legacy_puyo_tools-0.0.1 → legacy_puyo_tools-0.1.0}/uv.lock

@@ -106,6 +106,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/85/32/10bb5764d90a8eee674e9dc6f4db6a0ab47c8c4d0d83c27f7c39ac415a4d/click-8.2.1-py3-none-any.whl", hash = "sha256:61a3265b914e850b85317d0b3109c7f8cd35a670f963866005d6ef1d5175a12b", size = 102215, upload-time = "2025-05-20T23:19:47.796Z" },
 ]
 
+[[package]]
+name = "cloup"
+version = "3.0.7"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/86/c9/3c621e0b7898403556e807244104095df1132a6094384f80c272bba4e4e4/cloup-3.0.7.tar.gz", hash = "sha256:c852e0a0541aa433c6ab31a9b8b503f63d9881e91ddaf0384d6927965f2b421c", size = 229613, upload-time = "2025-03-15T00:34:10.224Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/45/2e/ccd754e473b972155f7e8ca60af373a8bc13ae951a5cb76363c43363e69d/cloup-3.0.7-py2.py3-none-any.whl", hash = "sha256:d3a431cf1e14d8835fe85608e02cc6ff7216f0a39e30d5e28618aa938003ddb4", size = 54602, upload-time = "2025-03-15T00:34:09.165Z" },
+]
+
 [[package]]
 name = "colorama"
 version = "0.4.6"
@@ -187,6 +199,8 @@ version = "0.0.1"
 source = { editable = "." }
 dependencies = [
     { name = "attrs" },
+    { name = "click" },
+    { name = "cloup" },
     { name = "lxml" },
 ]
 
@@ -203,6 +217,8 @@ dev = [
 [package.metadata]
 requires-dist = [
     { name = "attrs", specifier = ">=25.3.0" },
+    { name = "click", specifier = ">=8.2.1" },
+    { name = "cloup", specifier = ">=3.0.7" },
     { name = "lxml", specifier = ">=6.0.0" },
 ]
 

legacy_puyo_tools-0.0.1/PKG-INFO

@@ -1,34 +0,0 @@
-Metadata-Version: 2.4
-Name: legacy-puyo-tools
-Version: 0.0.1
-Summary: A tool to edit text for older Puyo Puyo games.
-Author-email: Samuel Wu <twopizza9621536@gmail.com>
-License-Expression: MIT
-License-File: LICENSE
-Requires-Python: >=3.13
-Requires-Dist: attrs>=25.3.0
-Requires-Dist: lxml>=6.0.0
-Description-Content-Type: text/markdown
-
-# Legacy Puyo Tools
-
-Supports Puyo Puyo 7 and possibly Puyo Puyo! 15th Anniversary `mtx` and `fpd`
-files. Puyo Puyo!! 20th Anniversary is still not supported yet. (Create an issue
-or pull request to support `fnt` and additional `mtx` controls). Also, legacy as
-in older Puyo Puyo games, not that this tool is decapitated.
-
-## Why
-
-The [Puyo Text Editor][1] can already do what Legacy Puyo Tools does and is the
-inspiration of this tool, but there are advantages to rewrite it in Python:
-
-- Better cross compatibility with Linux.
-- Don't have to update the language version every time it becomes End of Life.
-- Avoids the rigidness of using a pure object-oriented design.
-
-## License
-
-Under the MIT License. Based on [Puyo Text Editor][1] which is also under the
-MIT License.
-
-[1]: https://github.com/nickworonekin/puyo-text-editor

legacy_puyo_tools-0.0.1/README.md

@@ -1,22 +0,0 @@
-# Legacy Puyo Tools
-
-Supports Puyo Puyo 7 and possibly Puyo Puyo! 15th Anniversary `mtx` and `fpd`
-files. Puyo Puyo!! 20th Anniversary is still not supported yet. (Create an issue
-or pull request to support `fnt` and additional `mtx` controls). Also, legacy as
-in older Puyo Puyo games, not that this tool is decapitated.
-
-## Why
-
-The [Puyo Text Editor][1] can already do what Legacy Puyo Tools does and is the
-inspiration of this tool, but there are advantages to rewrite it in Python:
-
-- Better cross compatibility with Linux.
-- Don't have to update the language version every time it becomes End of Life.
-- Avoids the rigidness of using a pure object-oriented design.
-
-## License
-
-Under the MIT License. Based on [Puyo Text Editor][1] which is also under the
-MIT License.
-
-[1]: https://github.com/nickworonekin/puyo-text-editor

legacy_puyo_tools-0.0.1/REUSE.toml

@@ -1,15 +0,0 @@
-# SPDX-FileCopyrightText: 2025 Samuel Wu
-#
-# SPDX-License-Identifier: MIT-0
-
-version = 1
-
-[[annotations]]
-SPDX-FileCopyrightText = "2025 Samuel Wu"
-SPDX-License-Identifier = "MIT"
-path = ["docs/formats.md"]
-
-[[annotations]]
-SPDX-FileCopyrightText = "2025 Samuel Wu"
-SPDX-License-Identifier = "MIT-0"
-path = ["README.md", "uv.lock"]

legacy_puyo_tools-0.0.1/docs/formats.md

@@ -1,26 +0,0 @@
-# Formats
-
-Older Puyo Puyo games used multiple formats to store manzai text and character
-data. This document contains how each format is structured and encoded.
-
-## The `fpd` format
-
-The `fpd` format is a binary character table format used by the developers for
-Puyo Puyo! 15th Anniversary and Puyo Puyo 7 to convert characters from UTF-16
-little-endian into an index that is used by the `mtx` for text. Each character
-entry in the `fpd` is 3 bytes long and formatted as follows: `XX XX YY`. Where
-`XX XX` is the character encoded in UTF-16 little-endian and `YY` is the width
-of the character. The entries are placed next to each other, creating a
-zero-based index that is offset by multiples of `0x03`. I.e. the 1st character
-is at index `0x00`, the 2nd character is at index `0x03`, the 3rd character is
-at index `0x06`, etc.
-
-The `fpd` is not used by the games internally except for the Nintendo DS version
-of Puyo Puyo 7.
-
-## The `mtx` format
-
-<!-- TODO: Finish the mtx format for PP15 and PP7 -->
-<!-- TODO: Look at the mtx format for PP20 -->
-The `mtx` format is a binary-encoded format used by older Puyo games for
-storing character dialog and text.

legacy_puyo_tools-0.0.1/src/legacy_puyo_tools/cli.py

@@ -1,177 +0,0 @@
-"""A commandline application that interfaces with conversion tools.
-
-SPDX-FileCopyrightText: 2025 Samuel Wu
-SPDX-License-Identifier: MIT
-"""
-
-from __future__ import annotations
-
-import argparse
-import sys
-from codecs import BOM_UTF16_LE
-from collections.abc import Callable
-from importlib import metadata
-from pathlib import Path
-from typing import BinaryIO
-
-from attrs import define
-
-from legacy_puyo_tools.exceptions import FileFormatError
-from legacy_puyo_tools.fpd import Fpd
-from legacy_puyo_tools.mtx import Mtx
-
-
-@define
-class _CliNamespace(argparse.Namespace):
-    func: Callable[[type[_CliNamespace]], None]
-    input: BinaryIO
-    output: BinaryIO
-    unicode: BinaryIO
-    fpd: BinaryIO
-    version: bool
-
-
-def _create_fpd(args: _CliNamespace) -> None:
-    if args.input.read(2) != BOM_UTF16_LE:
-        raise FileFormatError(
-            f"{args.input.name} is not a UTF-16 little-endian encoded text"
-            "file."
-        )
-
-    if args.output:
-        Fpd.read_unicode(args.input).write_fpd(args.output)
-        return
-
-    path = Path(args.input.name).with_suffix("")
-
-    if path.suffix != ".fpd":
-        path = path.with_suffix(".fpd")
-
-    Fpd.read_unicode(args.input).write_fpd_to_path(path)
-
-
-def _create_mtx(args: _CliNamespace) -> None:
-    raise NotImplementedError()
-
-
-def _convert_fpd(args: _CliNamespace) -> None:
-    if args.output:
-        args.output.write(BOM_UTF16_LE)
-        Fpd.read_fpd(args.input).write_fpd(args.output)
-        return
-
-    path = Path(args.input.name).with_suffix("")
-
-    if path.suffix != ".fpd":
-        path = path.with_suffix(".fpd")
-
-    Fpd.read_fpd(args.input).write_unicode_to_path(path)
-
-
-def _convert_mtx(args: _CliNamespace) -> None:
-    if args.fpd:
-        fpd_data = Fpd.read_fpd(args.fpd)
-    else:
-        if args.unicode.read(2) != BOM_UTF16_LE:
-            raise FileFormatError(
-                f"{args.input.name} is not a UTF-16 little-endian encoded text"
-                "file."
-            )
-
-        fpd_data = Fpd.read_unicode(args.unicode)
-
-    if args.output:
-        Mtx.read_mtx(args.input).write_xml(args.output, fpd_data)
-        return
-
-    path = Path(args.input.name).with_suffix("")
-
-    if path.suffix != ".xml":
-        path = path.with_suffix(".xml")
-
-    Mtx.read_mtx(args.input).write_xml_to_file(path, fpd_data)
-
-
-def _create_parsers(main_parser: argparse.ArgumentParser) -> None:
-    shared_options = argparse.ArgumentParser(add_help=False)
-    shared_options.add_argument(
-        "input", type=argparse.FileType("rb"), help="input file"
-    )
-    shared_options.add_argument(
-        "-o", "--output", type=argparse.FileType("wb"), help="output file"
-    )
-
-    mtx_options = argparse.ArgumentParser(
-        add_help=False, parents=[shared_options]
-    )
-    mtx_options_group = mtx_options.add_mutually_exclusive_group(required=True)
-    mtx_options_group.add_argument(
-        "--fpd", type=argparse.FileType("rb"), help="fpd file"
-    )
-    mtx_options_group.add_argument(
-        "--unicode", type=argparse.FileType("rb"), help="unicode text file"
-    )
-
-    sub_parser = main_parser.add_subparsers()
-
-    create_parser = sub_parser.add_parser("create")
-    create_sub_parser = create_parser.add_subparsers(required=True)
-
-    create_fpd_parser = create_sub_parser.add_parser(
-        "fpd",
-        help="create a fpd file from a unicode text file",
-        parents=[shared_options],
-    )
-    create_fpd_parser.set_defaults(func=_create_fpd)
-
-    create_mtx_parser = create_sub_parser.add_parser(
-        "mtx", help="create a mtx file from a XML file", parents=[mtx_options]
-    )
-    create_mtx_parser.set_defaults(func=_create_mtx)
-
-    convert_parser = sub_parser.add_parser("convert")
-    convert_sub_parser = convert_parser.add_subparsers(required=True)
-
-    convert_fpd_parser = convert_sub_parser.add_parser(
-        "fpd",
-        help="convert a fpd file to a unicode file",
-        parents=[shared_options],
-    )
-    convert_fpd_parser.set_defaults(func=_convert_fpd)
-
-    convert_mtx_parser = convert_sub_parser.add_parser(
-        "mtx", help="convert a mtx file to XML file", parents=[mtx_options]
-    )
-    convert_mtx_parser.set_defaults(func=_convert_mtx)
-
-
-def main() -> None:
-    """Entry point for the commandline application."""
-    main_parser = argparse.ArgumentParser(
-        description="A conversion tool for files used by older Puyo games."
-    )
-    main_parser.add_argument(
-        "-v", "--version", help="show version", action="store_true"
-    )
-
-    _create_parsers(main_parser)
-
-    args = main_parser.parse_args(namespace=_CliNamespace)
-
-    if args.version is True:
-        package_name = "legacy-puyo-tools"
-        version = metadata.version(package_name)
-
-        print(f"{package_name} {version}")
-
-        sys.exit(0)
-
-    if not hasattr(args, "func"):
-        main_parser.print_help(sys.stderr)
-        sys.exit(1)
-
-    args.func(args)
-
-
-if __name__ == "__main__":
-    main()