Background

<p dir="auto">The International Patching System (IPS) patch format is a historically popular distribution format for ROM hacks. It's a <a href="http://old.smwiki.net/wiki/IPS_file_format" target="_blank" rel="noreferrer noopener" title="This link will take you away from hive.blog" class="external_link">very simple format, and a number of tools exist for creating IPS patches from binary data. I wanted to be able to create IPS patches programatically in Python scripts, however, and no existing library provided that support. So I made one. <p dir="auto">I got enough testing and polish done on the library that I chose to upload it to PyPI as a formal Python package. As such, a released version can be acquired by any Python user with <code>pip install ips-util. <h1>Links <ul> <li><a href="https://github.com/nleseul/ips_util" target="_blank" rel="noreferrer noopener" title="This link will take you away from hive.blog" class="external_link">Project GitHub repository <li><a href="https://pypi.org/project/ips-util/" target="_blank" rel="noreferrer noopener" title="This link will take you away from hive.blog" class="external_link">PyPI page <ul> <li><a href="https://github.com/nleseul" target="_blank" rel="noreferrer noopener" title="This link will take you away from hive.blog" class="external_link">My GitHub account <h1>Usage notes <p dir="auto">(Pretty much straight from the <a href="https://github.com/nleseul/ips_util/blob/master/README.md" target="_blank" rel="noreferrer noopener" title="This link will take you away from hive.blog" class="external_link">README.) <p dir="auto">To create a patch, using existing source and target binary files: <pre><code>> ips_util create "Super Mario World.smc" "Super Mario World [1337357_h4x_3v4r].smc" -o 1337_p47ch.ips <p dir="auto">To apply a patch to a binary file: <pre><code>> ips_util apply 1337_p47ch.ips "Super Mario World.smc" -o w00t.smc <p dir="auto">To dump the contents of a patch: <pre><code>> ips_util trace 1337_p47ch.ips <p dir="auto">The package can also be used within Python scripts to build IPS patches manually, as follows: <pre><code>from ips_util import Patch def this_is_my_patch(): patch = Patch() patch.add_record(0x1234, 999.to_bytes(2, byteorder='little')) # Max out some stat patch.add_rle_record(0x5678, b'\xea', 0x10) # NOP out a bunch of code with open('gavroche.ips', 'w+b') as f: f.write(patch.encode()) <h1>Testing <p dir="auto">The package includes unit tests (contained in the <code>ips_util/tests/test_patch.py script) to verify design requirements and some common edge cases in IPS format: <h2>Manually created patches <ul> <li>Verify that a basic patch produces the desired result (<code>test_patch_core) <li>Verify that a change made past the end of the original data will pad the result data as needed (<code>test_patch_padding) <li>Verify that the truncation syntax used by some IPS tools functions as intended (<code>test_patch_truncation) <li>Verify that the library generates an error when the starting address of a patch record is exactly 0x454f46 ('EOF') (<code>test_patch_eof_edge_case) <h2>Patches created from source and target binary data (the <code>Patch.create() API) <ul> <li>Verify that the patch created from binary data reproduces the desired target data when applied (<code>test_create_equal_length) <li>Verify that creating a patch correctly handles padding when the target data is longer than the source data (<code>test_create_padded_length) <ul> <li>... even when the padded data contains only zeros. (<code>test_create_padded_length_all_zero) <li>Verify that creating a patch correctly handles truncation when the target data is shorter than the source data (<code>test_create_truncated_length) <li>Verify that when a difference occurs at the address 0x454f46, the generated patch shifts that address to avoid the EOF error noted above (<code>test_create_eof_edge_case) <li>Verify that an error is generated when the binary data provided is longer than the maximum supported address (<code>test_create_address_overflow) <li>Verify that when creating a patch, differences longer than the maximum supported size are handled gracefully (<code>test_create_size_overflow) <ul> <li>... even when the record is run-length encoded (<code>test_create_rle_size_overflow)