{"id":16909479,"url":"https://github.com/Calcoph/hexpyt","last_synced_at":"2025-12-18T07:30:18.669Z","repository":{"id":45621892,"uuid":"513881969","full_name":"Calcoph/hexpyt","owner":"Calcoph","description":"Script to convert ImHex patterns into python","archived":false,"fork":false,"pushed_at":"2023-10-07T18:10:03.000Z","size":183,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-14T18:56:05.734Z","etag":null,"topics":["imhex"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Calcoph.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-07-14T11:53:55.000Z","updated_at":"2024-08-04T21:42:49.000Z","dependencies_parsed_at":"2023-01-18T16:43:49.675Z","dependency_job_id":null,"html_url":"https://github.com/Calcoph/hexpyt","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Calcoph%2Fhexpyt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Calcoph%2Fhexpyt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Calcoph%2Fhexpyt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Calcoph%2Fhexpyt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Calcoph","download_url":"https://codeload.github.com/Calcoph/hexpyt/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239693246,"owners_count":19681621,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["imhex"],"created_at":"2024-10-13T18:55:53.243Z","updated_at":"2025-12-18T07:30:18.634Z","avatar_url":"https://github.com/Calcoph.png","language":"Python","funding_links":[],"categories":["Unofficial"],"sub_categories":[],"readme":"Convert your hexpat (ImHex's pattern language) scripts to python scripts.\n\nYou can see the documentation of the language [here](https://imhex.werwolv.net/docs/): [ImHex docs.](https://imhex.werwolv.net/docs/)\n\nThis project is incomplete so it won't parse entire scripts completely. It is not forgiving with the formatting of the input file, you can see valid input files in the `examples` folder. `bad_and_good_examples.pat` and `bad_and_good_examples.py` can act as a quick troubleshooting guide.\n\n# Features\n* Turn structs into python classes\n* Turn bitfields into python classes\n* Translate some basic expressions (manual intervention probably needed)\n* Dollar class that works like ImHex's $\n* @ operator that works like ImHex's @ (see [Using translated structs](#using-translated-structs))\n* Read from multiple files at the same time (By making multiple Dollar objects)\n\nDocstrings contain the original hexpat syntax. Image is from examples/bin_file.py\n\n![Demostration of docstring in vscode with syntax highlighting](resources/HoverFile.png)\n\nIf you want syntax highlighting in vscode (like in the image), you can use [this extension](https://github.com/Calcoph/vscode-hexpat)\n\n# Installation\nJust download `main.py` and `primitives.py`. You will need a modern version of python3 (so at least it supports f-strings)\n\n# Usage\n## Usage of the translator\n### Option 1\nImport it into another python file and use the `translate_file` function. It's strongly recommended that you rename the file in that case\n```python\nfrom main import translate_file\n\ntranslate_file(\"examples/bin_file.pat\", \"examples/bin_file.py\")\n```\n### Option 2\nEdit `main.py` to enter the file paths.\n\nAt the end of the file, after \u003cif \\_\\_name\\_\\_ == \"\\_\\_main\\_\\_\"\u003e\n```\ninput_file_path = \"\"\noutput_file_path = \"\"\n```\nThen run it\n```console\n\u003e python main.py\n```\n\n## Usage of the translated files\nThe first thing you will need to do if you want to read a file is follow the instructions in the first lines of the translated file. It looks something like this:\n```python\n# Template to read from a file. follow the instructions.\n# _dollar___offset has this name so it doesn't clash with others. Feel free to rename it. \nif True: # Change this from \"if True\" to \"if False\", then put the file path below.\n    byts = b''\nelse:\n    file_path = \"\" # Put the file path here and change the above \"if True\" to \"if False\".\n    with open(file_path, \"rb\") as f:\n        byts = f.read()\n_dollar___offset = Dollar(0x00, byts)\n# End of template\n```\n\nFrom this point on I'll assume you have renamed `_dollar___offset` to `dollar`\n\nRun the file to make sure it has been translated correctly\n```terminal\n\u003e python translated_file.py\n```\nIf any error ocurs, solve it manually.\n\n### Using translated structs\nThe syntaxis for this is similar to ImHex:\n```python\nnew_var = MyStruct() @ dollar\n\n# Or\nnew_var = MyStruct() @ Dollar(0x98, byts) # The @ operator doesn't work on python's ints, so you have to convert it to a Dollar\n\n# Or\npointer = u8() @ Dollar(0x98, byts)\nnew_struct = MyStruct() @ pointer # This works since u8 is a hexpyt type that was created with a @ operator\n\n# This won't work\npointer = u8(0x98) # u8 was created with a value, so it doesn't have a reference to \"byts\"\nnew_struct = MyStruct() @ pointer\n\n# It's recommended to type hint so you can see the original hexpat definition by hovering over the type hint (on most IDEs/text editors)\nnew_var: MyStruct = MyStruct() @ dollar\n```\n\nBe careful with the order of operations, since @ has a high priority:\n```python\nnew_var = MyStruct() @ dollar + 1 # Will crash, since it will do (MyStruct() @ dollar) + 1\nnew_var = MyStruct() @ (dollar + 1) # Works as expected\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCalcoph%2Fhexpyt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCalcoph%2Fhexpyt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCalcoph%2Fhexpyt/lists"}