{
    "info": {
        "author": "Thomas Prescott",
        "author_email": "tcprescott@gmail.com",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 5 - Production/Stable",
            "License :: OSI Approved :: Apache Software License",
            "Operating System :: OS Independent",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: 3.7"
        ],
        "description": "# pyz3r for Python 3.6/3.7!\nPyz3r is an unofficial python abstraction library for interacting with the [alttpr.com](https://alttpr.com) API.\n\nThis allows developers to create applications that not only generate games on [alttpr.com](https://alttpr.com),\nbut also create the ROM as well using the patch data provided by the website.\n\n## Installation\nThis module is available on PyPI.  It can be installed via pip:\n\n`pip install pyz3r`\n\n## Compatiblity\nThis library has been tested on both Linux (Centos 7) and Windows on Python 3.6.  Python 3.7 should also work, though it hasn't been as extensively tested.  An internet connection is required so it can communicate with alttpr.com.\n\n## Disclaimer(s)\nThis is an unofficial tool.  Please do not submit bug reports on the official ALTTPR repository Github for issues that\nare related to the use of this library!\n\nIf something is broken, please make sure it isn't related to this library before posting the bug report on the\nalttp_vt_randomizer repository.  Feel free to post the bug here first if you're unsure.\n\nUsing this library to patch a ROM for racing may not be permitted.\nIts best to check with an official before using it for racing.\n\nFinally, this library may break when new versions of the Link to the Past Randomizer are released.  This version\nwas tested with v30, however it may cease to function in later releases.  If it does, please submit a Github issue!\n\n\n## Usage\nBasic usage is fairly simple.\n\nFirst you'll need to either generate a new seed or use the hash of a previous seed to get a game.\n\n### Initiating an Item Randomizer seed\nThe below example will generate an item randomizer game with a list of settings:\n```python\nimport pyz3r\n\nseed = pyz3r.alttpr(\n    randomizer='item', # optional, defaults to item\n    settings={\n        \"difficulty\": \"hard\",\n        \"enemizer\": False,\n        \"logic\": \"NoGlitches\",\n        \"mode\": \"open\",\n        \"spoilers\": False,\n        \"tournament\": True,\n        \"variation\": \"key-sanity\",\n        \"weapons\": \"uncle\",\n        \"lang\": \"en\"\n    }\n)\n```\n\nThis will give you a list of item randomizer options as a dictionary:\n```python\npyz3r.alttpr(randomizer='item').settings()\n```\n\n### Intiating an Entrance Shuffle seed\nThis will generate an entrance shuffle game:\n```python\nimport pyz3r\n\nseed = pyz3r.alttpr(\n    randomizer='entrance',\n    settings={\n        \"logic\":\"NoGlitches\",\n        \"difficulty\":\"normal\",\n        \"variation\":\"retro\",\n        \"mode\":\"open\",\n        \"goal\":\"ganon\",\n        \"shuffle\":\"restricted\",\n        \"tournament\":True,\n        \"spoilers\":False,\n        \"enemizer\":False,\n        \"lang\":\"en\"\n    }\n)\n```\n\nThis will give you a list of item randomizer options as a dictionary:\n```python\npyz3r.alttpr(randomizer='entrance').settings()\n```\n\n### Loading an already generated game\nIf the game you want to work with has already been generated, you can load the hash like this:\n\n```python\nseed = pyz3r.alttpr(\n    hash='zDvxWLLEMa'\n)\n```\n\n### Getting the code display and URL\n\nThis will return to you a list of strings with the \"code\" that appears on the file select screen.\n\n```python\ncode = seed.code()\nprint(\"Hash: [{hash}]\".format(\n    hash = ' | '.join(code)\n))\n```\nOutput:\n`Hash: [Heart | Empty Bottle | Somaria | Ice Rod | Boots]`\n\nYou can also get the url quickly as well:\n\n```python\nurl = seed.url\nprint(\"Permalink: {url}\".format(\n    url = url\n))\n```\nOutput:\n`Permalink: https://alttpr.com/h/zDvxWLLEMa`\n\n\n### Accessing seed data\n\nYou can access the seed's data via the `data` variable in the alttpr class.  The example below will print the dictionary that has the seed's spoiler data (if available).\n\n```python\nprint(seed.data['spoiler'])\n```\n\n### Patching\n\nThis is the meat and potatoes of the library.  There are two ways, the easy and advanced way.\n\n#### Easy patching\n\nYou'll first want to read your unmodified Japan 1.0 ROM of Link to the Past.  `read_rom()` will checksum the file to ensure its the correct ROM.\n\n```python\nbase_rom = pyz3r.romfile.read(\"path/to/Zelda no Densetsu - Kamigami no Triforce (Japan).sfc\")\n```\n\n`base_rom` will be an array of integers representing the bytes of the original ROM.\n\nYou'll then want to use `create_patched_game` to apply all of the patches required to randomize and customize the ROM.\n```python\npatched_rom = seed.create_patched_game(\n    base_rom,  \n    heartspeed='normal',\n    heartcolor='red',\n    spritename='Link', #can be any sprite listed at https://alttpr.com/sprites\n    music=False # true or false, defaults true\n)\n```\n\nHere you can customize the following:\n\n0. `patchrom_array` - Required.  This is an array of bits that have your original Japan 1.0 ROM.  The `pyz3r.romfile.read()` function.\n1. `heartspeed` - Optional. The low health beep speed.  Acceptable values are `'off'`, `'quarter'`, `'half'`, `'double'`, or `'normal'`.  Defaults is `'normal'`.\n2. `heartcolor` - Optional. The color of your hearts.  Acceptable values are `'red'`, `'blue'`, `'green'`, or `'yellow'`.  Default is `'red'`.\n3. `spritename` - Optional. The sprite to use.  Acceptable values are the `name` keys in the json file at https://alttpr.com/sprites.  Default is `'Link'`.\n4. `music` - Optional. Whether music should play.  Acceptable values are `True` and `False`. `False` allows MSU-1 music to work correctly.  Default is `True`.\n\nThe result of `create_patched_game` is an array of integers representing the fully patched ROM.\n\nFinally, you can write the ROM to a new file:\n```python\npyz3r.romfile.write(patched_rom, \"path/to/patched_rom.sfc\")\n```\n\n#### Advanced patching\nIf you have a patched game, and just want to customize the already patched game, this library lets you do that too.\n\nThe following example will let you bring in an already patched game and let you customize the heart speed, heart color, sprite, and music.\n\n```python\nimport pyz3r\nfrom pyz3r.patch import patch\n\nrom = pyz3r.romfile.read('path/to/rom.sfc',verify_checksum=False)\n\n#apply the heart speed change\nrom = patch.apply(\n    rom=rom,\n    patches=patch.heart_speed('half')\n)\n\n#apply the heart color change\nrom = patch.apply(\n    rom=rom,\n    patches=patch.heart_color('blue')\n)\n\n#apply the sprite, retrieves a sprite from the alttpr website\nrom = patch.apply(\n    rom=rom,\n    patches=patch.sprite(\n        spr=pyz3r.alttpr().get_sprite('Negative Link')\n    )\n)\n\n#apply the music\nrom = patch.apply(\n    rom=rom,\n    patches=patch.music(True)\n)\n\npyz3r.romfile.write(rom,'path/to/patched_rom.sfc')\n```\n\n### Using the customizer\nThe ALttPR website has a feature where a player may customize a game, including choosing starting equipment, item locations, game settings, drops and prizepack customization.  This library has a feature that allows you to generate games using the settings saved on alttpr.com's customizer.\n\nTo use it,  you'll want to read a `customizer-settings.json` file that was saved from alttpr.com, then use the provided function `customizer.convert2settings()` to convert the json file to something that can be be used for game generation.\n\n`tournament` can be set to True to generate the game as a race rom.  This will cause the spoiler log to be unavailable,\nalong with scrambling the item table within the ROM.\n\n```python\nimport json\nimport pyz3r\nfrom pyz3r.customizer import customizer\n\nf = open('customizer-settings.json', \"r\")\ncustomizer_settings = json.loads(f.read())\nf.close()\n\nseed = pyz3r.alttpr(\n    randomizer='item',\n    settings=customizer.convert2settings(customizer_save=customizer_settings, tournament=False)\n)\n```\n\nAs of v30, the customizer only works with the item randomizer.  There may be unexpected results if you try this with the entrance randomizer.\n\n### Async Support\nThis library can also be used using asyncio (via the aiofiles and aiohttp library), which may be useful for bots that use asyncio (such as discord.py).  The syntax is very similar, with a two notable differences.\n\n```python\nimport pyz3r\nimport asyncio\n\nasync def test_retrieve_game():\n    seed = await pyz3r.alttpr(\n        hash='zDvxWLLEMa'\n    )\n\n    print(\"Permalink: {url}\".format(\n        url = seed.url\n    ))\n    print(\"Hash: [{hash}]\".format(\n        hash = ' | '.join(await seed.code())\n    ))\n\n    print(seed.data['spoiler'])\n\n    jpn10rom = await pyz3r.romfile.read(\"base_rom/Zelda no Densetsu - Kamigami no Triforce (Japan).sfc\")\n    patched_rom = await seed.create_patched_game(\n        patchrom_array = jpn10rom,  \n        heartspeed=None, #can be off, quarter, half, double or normal.\n        heartcolor='red', #can be red, \n        spritename='Negative Link', #can be any sprite listed at https://alttpr.com/sprites\n        music=False # true or false, defaults true\n        )\n    await pyz3r.romfile.write(patched_rom, \"outputs/patched_rom.sfc\")\n\nif __name__ == '__main__':\n    loop = asyncio.get_event_loop()\n    loop.run_until_complete(test_retrieve_game())\n```\n\nThe most notable changes are using asyncio's await syntax and using `pyz3r.alttpr()` and `pyz3r.romfile` instead.\n\n## To do\n\n0. Add a feature to verify a settings dictionary before attempting to generate a game.  This may become the default behavior, with the ability to override it.  This could also just be a separate function that could be invoked as well.\n1. Right now Quickswap and Menu Speed options are not available. If they were, the behavior of this library would be for them **not** to function on race seeds.  I figure few people use these features, so they won't be in the initial release of pyz3r.\n2. Add a shortcut for pulling the data for the daily game.  This would likely have to be scraped since it doesn't appear to be any API endpoint for this.\n3. Improve logging.  Right now this library does zero logging on its own, which should be fixed.\n4. Add unit tests.\n\n## Credits and shoutouts\n\n0. Veetorp, Karkat, ChristosOwen, Smallhacker, and Dessyreqt for making an incredible randomizer.\n1. The mods at the ALTTPR discord (https://discord.gg/alttprandomizer).\n2. This work is dedicated to my father.  May he rest in peace.\n3. Jaysee87 for his input into specific functionality, and suggesting asyncio support for usage with discord bots.\n\nGithub for alttp_vt_randomizer: https://github.com/sporchia/alttp_vt_randomizer",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/tcprescott/pyz3r",
        "keywords": "",
        "license": "",
        "maintainer": "",
        "maintainer_email": "",
        "name": "pyz3r",
        "package_url": "https://pypi.org/project/pyz3r/",
        "platform": "",
        "project_url": "https://pypi.org/project/pyz3r/",
        "project_urls": {
            "Homepage": "https://github.com/tcprescott/pyz3r"
        },
        "release_url": "https://pypi.org/project/pyz3r/4.0.0/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "A python module for interacting with alttpr.com, such as generating new z3r games, and patching existing games.",
        "version": "4.0.0"
    },
    "last_serial": 5833462,
    "releases": {
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "d78cde4ae9335e5522643f55addae651",
                    "sha256": "acde8e1ceabeaed85e937f81333405336776a2920e78eeb1ca465bed416ef7e4"
                },
                "downloads": -1,
                "filename": "pyz3r-1.0.0-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "d78cde4ae9335e5522643f55addae651",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 11133,
                "upload_time": "2018-12-31T06:02:04",
                "url": "https://files.pythonhosted.org/packages/eb/a9/fb7f1035c2fa598e5fbb0af7f9b1aa9bd8dd2c85974143068ff580d50a6a/pyz3r-1.0.0-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "cb3a808cbf331c08f050dc0513339ef6",
                    "sha256": "9b56664232ed4b132b57081b2ebda4a71a071aeeeafd7e69f05310dc792c6fe0"
                },
                "downloads": -1,
                "filename": "pyz3r-1.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "cb3a808cbf331c08f050dc0513339ef6",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 7286,
                "upload_time": "2018-12-31T06:02:06",
                "url": "https://files.pythonhosted.org/packages/20/9f/d22e730ff7a1e4dea7cd237f5dae9301951080e733a32c7bf3fbbb49487f/pyz3r-1.0.0.tar.gz"
            }
        ],
        "1.0.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8f9fbca516b1cb9a72ae2e3216ab3360",
                    "sha256": "4f7d4bb8caaec8887631770fafd1a8055138cf6e41aabe6d5384b4421d2a63ee"
                },
                "downloads": -1,
                "filename": "pyz3r-1.0.1-py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "8f9fbca516b1cb9a72ae2e3216ab3360",
                "packagetype": "bdist_wheel",
                "python_version": "py3",
                "requires_python": null,
                "size": 11250,
                "upload_time": "2019-03-14T04:21:24",
                "url": "https://files.pythonhosted.org/packages/33/2f/1e53541e31f8e7adb4e5f0cf9df0cfab76c6adda8864a4b65dec72974936/pyz3r-1.0.1-py3-none-any.whl"
            },
            {
                "comment_text": "",
                "digests": {
                    "md5": "55649179ca1223e6ae5a06581b078ece",
                    "sha256": "4169fec69e6e7c38c04e40c72c22e6c06e578632682fc4e5fff6be9a84a7d20e"
                },
                "downloads": -1,
                "filename": "pyz3r-1.0.1.tar.gz",
                "has_sig": false,
                "md5_digest": "55649179ca1223e6ae5a06581b078ece",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 7382,
                "upload_time": "2019-03-14T04:21:25",
                "url": "https://files.pythonhosted.org/packages/ce/97/0918952c9221a76c9d0731463e733b9ab91c854645387f831be88701adb4/pyz3r-1.0.1.tar.gz"
            }
        ],
        "2.0.6": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "d1c0136574156ae13de838df1e6e5de7",
                    "sha256": "798f43e4bb9cb1e4770768f410b59c7789eb3aa8029d3c36b44d29e6846234fb"
                },
                "downloads": -1,
                "filename": "pyz3r-2.0.6.tar.gz",
                "has_sig": false,
                "md5_digest": "d1c0136574156ae13de838df1e6e5de7",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 7943,
                "upload_time": "2019-03-16T18:03:02",
                "url": "https://files.pythonhosted.org/packages/32/26/df7a71f6bcd6b980581c6efdc055dd2e215406a0208ebed7f49f767f1165/pyz3r-2.0.6.tar.gz"
            }
        ],
        "2.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "4c78ec48dd4506fb7747fbcbe61480f3",
                    "sha256": "9872d4274c3d1d2a702e6ac4c727b278bc34b10e9a7bf93ec0498870827e18f5"
                },
                "downloads": -1,
                "filename": "pyz3r-2.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "4c78ec48dd4506fb7747fbcbe61480f3",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 11659,
                "upload_time": "2019-03-16T22:12:21",
                "url": "https://files.pythonhosted.org/packages/ff/15/7685f2ce8bb579aa3231f4b8df225d11712518e7d31146bd8cb26df4b068/pyz3r-2.1.0.tar.gz"
            }
        ],
        "2.1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "eccaefc38ebf523a16e1d83eaf90055a",
                    "sha256": "3b27ac7c4a6bb62f130314b2a897c007cc37ed1124837beb877d267381b50c8f"
                },
                "downloads": -1,
                "filename": "pyz3r-2.1.1.tar.gz",
                "has_sig": false,
                "md5_digest": "eccaefc38ebf523a16e1d83eaf90055a",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 13067,
                "upload_time": "2019-03-17T02:16:29",
                "url": "https://files.pythonhosted.org/packages/b9/a4/507c3cdf521403f220140b53848298af0d129a606cf16b38114d96235d05/pyz3r-2.1.1.tar.gz"
            }
        ],
        "2.2.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "4d9fd00090a91d80f7103c7f4fd00cdd",
                    "sha256": "50bd427fda93a8c82aa4f67718d03f77b7b52a13f842a10e48025c9cb587de4a"
                },
                "downloads": -1,
                "filename": "pyz3r-2.2.0.tar.gz",
                "has_sig": false,
                "md5_digest": "4d9fd00090a91d80f7103c7f4fd00cdd",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 18621,
                "upload_time": "2019-03-17T20:36:44",
                "url": "https://files.pythonhosted.org/packages/a8/0e/944f0835e686e8ab3adcf5ad4eea97dbb3133d99baa08bc6e3d284ac6d78/pyz3r-2.2.0.tar.gz"
            }
        ],
        "2.2.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "a6dcba52c4b3ffc26902910d2483b3f4",
                    "sha256": "261a257b2e627e96aa33de3dc7b01641fd46001e64ef48cc02be3201c088d8aa"
                },
                "downloads": -1,
                "filename": "pyz3r-2.2.1.tar.gz",
                "has_sig": false,
                "md5_digest": "a6dcba52c4b3ffc26902910d2483b3f4",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 18688,
                "upload_time": "2019-03-20T01:04:25",
                "url": "https://files.pythonhosted.org/packages/77/40/b7569ae6c13063adb4519d279089e90091807f569784ebb5629585813c8b/pyz3r-2.2.1.tar.gz"
            }
        ],
        "3.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "35d90ae3ecc8b91041bf813ccc5068e3",
                    "sha256": "7364f58e5a386d8898d04a323750701e3e39f76e01eb18ac82454fe25f512678"
                },
                "downloads": -1,
                "filename": "pyz3r-3.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "35d90ae3ecc8b91041bf813ccc5068e3",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 18744,
                "upload_time": "2019-04-08T02:42:02",
                "url": "https://files.pythonhosted.org/packages/bc/a9/01b108e828ae9e32d668931762e2690e11c063e37f126662766db9b4d5be/pyz3r-3.0.0.tar.gz"
            }
        ],
        "3.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "6ef348c7650dfaf9a889b26789902b7d",
                    "sha256": "7aab1935f2f84b2997edbcd1099453238eba5a9f78c8e783c9aaac8005dbf541"
                },
                "downloads": -1,
                "filename": "pyz3r-3.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "6ef348c7650dfaf9a889b26789902b7d",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 19307,
                "upload_time": "2019-07-31T22:36:33",
                "url": "https://files.pythonhosted.org/packages/8c/96/f8d395465ba24fc2e72c2c3362350743fdcc1f69f56c07c8fc064e430f05/pyz3r-3.1.0.tar.gz"
            }
        ],
        "3.1.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "0a84d2df806c04bbed8cea6d0fd719a7",
                    "sha256": "75902e3285a72fb291f58ee01b63ae16f8097aee47a80d0e059116da1f83928c"
                },
                "downloads": -1,
                "filename": "pyz3r-3.1.2.tar.gz",
                "has_sig": false,
                "md5_digest": "0a84d2df806c04bbed8cea6d0fd719a7",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 19434,
                "upload_time": "2019-08-01T01:22:05",
                "url": "https://files.pythonhosted.org/packages/8f/f5/3f8f2c9576ae45307df4818b7ceacf1bec7e3bed2a89b1359d3aacd6748e/pyz3r-3.1.2.tar.gz"
            }
        ],
        "4.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "a506b228e38f4e12e759eb338d7a6bb0",
                    "sha256": "d5248af413d2aee675428d6bc7bb29e7610c8e526c0692a354ae608695dac609"
                },
                "downloads": -1,
                "filename": "pyz3r-4.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "a506b228e38f4e12e759eb338d7a6bb0",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 18283,
                "upload_time": "2019-09-16T01:14:12",
                "url": "https://files.pythonhosted.org/packages/f6/e8/4b91390005dd465baf3f1ab89cac74fd383bc2c1be4e15af7f2f1d0c434d/pyz3r-4.0.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "a506b228e38f4e12e759eb338d7a6bb0",
                "sha256": "d5248af413d2aee675428d6bc7bb29e7610c8e526c0692a354ae608695dac609"
            },
            "downloads": -1,
            "filename": "pyz3r-4.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "a506b228e38f4e12e759eb338d7a6bb0",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 18283,
            "upload_time": "2019-09-16T01:14:12",
            "url": "https://files.pythonhosted.org/packages/f6/e8/4b91390005dd465baf3f1ab89cac74fd383bc2c1be4e15af7f2f1d0c434d/pyz3r-4.0.0.tar.gz"
        }
    ]
}