{"id":19512690,"url":"https://github.com/guyingbo/iofree","last_synced_at":"2025-04-26T04:31:38.922Z","repository":{"id":53459298,"uuid":"145556193","full_name":"guyingbo/iofree","owner":"guyingbo","description":"iofree is an easy-to-use and powerful library to help you implement network protocols and binary parsers.","archived":false,"fork":false,"pushed_at":"2025-01-02T07:32:04.000Z","size":73,"stargazers_count":10,"open_issues_count":3,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-04T08:02:17.288Z","etag":null,"topics":["binary-parser","io-free","parser","protocols","sans-io"],"latest_commit_sha":null,"homepage":"https://github.com/guyingbo/iofree","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/guyingbo.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-21T11:44:17.000Z","updated_at":"2025-01-20T01:40:37.000Z","dependencies_parsed_at":"2024-11-10T23:27:39.685Z","dependency_job_id":"d10a6381-6ac9-4c69-8fc2-41433c0ccfac","html_url":"https://github.com/guyingbo/iofree","commit_stats":{"total_commits":64,"total_committers":3,"mean_commits":"21.333333333333332","dds":0.078125,"last_synced_commit":"2fb68a386f4a55ae96c460c354f6598bd1a702b1"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guyingbo%2Fiofree","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guyingbo%2Fiofree/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guyingbo%2Fiofree/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guyingbo%2Fiofree/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guyingbo","download_url":"https://codeload.github.com/guyingbo/iofree/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250931030,"owners_count":21509805,"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":["binary-parser","io-free","parser","protocols","sans-io"],"created_at":"2024-11-10T23:27:18.551Z","updated_at":"2025-04-26T04:31:38.584Z","avatar_url":"https://github.com/guyingbo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# iofree\n\n[![Build Status](https://travis-ci.org/guyingbo/iofree.svg?branch=master)](https://travis-ci.org/guyingbo/iofree)\n[![Documentation Status](https://readthedocs.org/projects/iofree/badge/?version=latest)](https://iofree.readthedocs.io/en/latest/?badge=latest)\n[![Python Version](https://img.shields.io/pypi/pyversions/iofree.svg)](https://pypi.python.org/pypi/iofree)\n[![Version](https://img.shields.io/pypi/v/iofree.svg)](https://pypi.python.org/pypi/iofree)\n[![Format](https://img.shields.io/pypi/format/iofree.svg)](https://pypi.python.org/pypi/iofree)\n[![License](https://img.shields.io/pypi/l/iofree.svg)](https://pypi.python.org/pypi/iofree)\n[![codecov](https://codecov.io/gh/guyingbo/iofree/branch/master/graph/badge.svg)](https://codecov.io/gh/guyingbo/iofree)\n\n`iofree` is an easy-to-use and powerful library to help you implement network protocols and binary parsers.\n\n## Installation\n\n~~~\npip install iofree\n~~~\n\n## Advantages\n\nUsing iofree, you can:\n\n* define network protocols and file format in a clear and precise manner\n* parse both binary streams and files\n\n## Documentation\n\n### Basic Usage\n\n```python\n\u003e\u003e\u003e from iofree import schema\n\u003e\u003e\u003e schema.uint8(1)\nb'\\x01'\n\u003e\u003e\u003e schema.uint32be(3)\nb'\\x00\\x00\\x00\\x03'\n\u003e\u003e\u003e schema.uint32be.parse(b'\\x00\\x00\\x00\\x03')\n3\n```\n\n### Tutorial 1: a simple parser\n\n```python\n\u003e\u003e\u003e class Simple(schema.BinarySchema):\n...     a = schema.uint8\n...     b = schema.uint32be # \"be\" for big-endian\n...\n\u003e\u003e\u003e Simple(1, 3).binary\nb'\\x01\\x00\\x00\\x00\\x03'\n\u003e\u003e\u003e binary = _\n\u003e\u003e\u003e Simple.parse(binary)\n\u003cSimple(a=1, b=3)\u003e\n```\n\n### Built-in units:\n\ncommonly used number units:\n\n* int8 uint8\n* int16 int16be uint16 uint16be\n* int24 int24be uint24 uint24be\n* int32 int32be uint32 uint32be\n* int64 int64be uint64 uint64be\n* float16 float16be\n* float32 float32be\n* float64 float64be\n\nsimple units:\n\n* Bytes\n* String\n* EndWith\n\ncomposite units:\n\n* LengthPrefixedBytes\n* LengthPrefixedString\n* LengthPrefixedObjectList\n* LengthPrefixedObject\n* MustEqual\n* Switch\n* SizedIntEnum\n* Convert\n* Group\n\n[API docs](https://iofree.readthedocs.io/en/latest/index.html)\n\nHere is a real life example [definition](https://github.com/guyingbo/iofree/blob/master/iofree/contrib/socks5.py) of socks5 client request, you can see the following code snippet:\n\n```python\nclass Socks5ClientRequest(schema.BinarySchema):\n    ver = schema.MustEqual(schema.uint8, 5)\n    cmd = schema.SizedIntEnum(schema.uint8, Cmd)\n    rsv = schema.MustEqual(schema.uint8, 0)\n    addr = Addr\n```\n\n### Tutorial 2: define socks5 address format\n\n```python\nIn [1]: import socket\n   ...: from iofree import schema\n   ...:\n   ...:\n   ...: class Addr(schema.BinarySchema):\n   ...:     atyp: int = schema.uint8\n   ...:     host: str = schema.Switch(\n   ...:         \"atyp\",\n   ...:         {\n   ...:             1: schema.Convert(\n   ...:                 schema.Bytes(4), encode=socket.inet_aton, decode=socket.inet_ntoa\n   ...:\n   ...:             ),\n   ...:             4: schema.Convert(\n   ...:                 schema.Bytes(16),\n   ...:                 encode=lambda x: socket.inet_pton(socket.AF_INET6, x),\n   ...:                 decode=lambda x: socket.inet_ntop(socket.AF_INET6, x),\n   ...:             ),\n   ...:             3: schema.LengthPrefixedString(schema.uint8),\n   ...:         },\n   ...:     )\n   ...:     port: int = schema.uint16be\n   ...:\n\nIn [2]: addr = Addr(1, '172.16.1.20', 80)\n\nIn [3]: addr\nOut[3]: \u003cAddr(atyp=1, host='172.16.1.20', port=80)\u003e\n\nIn [4]: addr.binary\nOut[4]: b'\\x01\\xac\\x10\\x01\\x14\\x00P'\n\nIn [5]: Addr.parse(addr.binary)\nOut[5]: \u003cAddr(atyp=1, host='172.16.1.20', port=80)\u003e\n```\n\nA complete socks5 Addr [definition](https://github.com/guyingbo/iofree/blob/master/iofree/contrib/common.py)\n\n## Projects using iofree\n\n* [Shadowproxy](https://github.com/guyingbo/shadowproxy)\n    * [socks5 models](https://github.com/guyingbo/iofree/blob/master/iofree/contrib/socks5.py) and [socks5 protocol](https://github.com/guyingbo/shadowproxy/blob/master/shadowproxy/protocols/socks5.py)\n    * [shadowsocks parser](https://github.com/guyingbo/shadowproxy/blob/master/shadowproxy/proxies/shadowsocks/parser.py)\n    * [shadowsocks aead parser](https://github.com/guyingbo/shadowproxy/blob/master/shadowproxy/proxies/aead/parser.py)\n* [python tls1.3](https://github.com/guyingbo/tls1.3)\n    * [TLS1.3 models](https://github.com/guyingbo/tls1.3/blob/master/tls/models.py) and [protocol](https://github.com/guyingbo/tls1.3/blob/master/tls/session.py)\n\n## References\n\n`iofree` parser is inspired by project [ohneio](https://github.com/acatton/ohneio).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguyingbo%2Fiofree","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguyingbo%2Fiofree","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguyingbo%2Fiofree/lists"}