{"id":13802058,"url":"https://github.com/dogtopus/minipb","last_synced_at":"2025-12-30T01:18:56.472Z","repository":{"id":56672457,"uuid":"166918007","full_name":"dogtopus/minipb","owner":"dogtopus","description":"Lightweight Protocol Buffer serialize/deserialize library","archived":false,"fork":false,"pushed_at":"2023-03-28T21:02:27.000Z","size":110,"stargazers_count":52,"open_issues_count":5,"forks_count":6,"subscribers_count":7,"default_branch":"master","last_synced_at":"2024-11-14T15:57:18.519Z","etag":null,"topics":["micropython","protobuf"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dogtopus.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}},"created_at":"2019-01-22T03:05:02.000Z","updated_at":"2024-10-24T15:34:45.000Z","dependencies_parsed_at":"2024-01-29T19:30:23.999Z","dependency_job_id":"4afffa82-1ca9-4899-892f-4e776c5dae94","html_url":"https://github.com/dogtopus/minipb","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dogtopus%2Fminipb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dogtopus%2Fminipb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dogtopus%2Fminipb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dogtopus%2Fminipb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dogtopus","download_url":"https://codeload.github.com/dogtopus/minipb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225217947,"owners_count":17439712,"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":["micropython","protobuf"],"created_at":"2024-08-04T00:01:34.525Z","updated_at":"2025-12-30T01:18:56.430Z","avatar_url":"https://github.com/dogtopus.png","language":"Python","funding_links":[],"categories":["Libraries"],"sub_categories":["Communications"],"readme":"# MiniPB\n\nMini Protobuf library in pure Python.\n\n![Lint and Run Test Suite](https://github.com/dogtopus/minipb/workflows/Lint%20and%20Run%20Test%20Suite/badge.svg)\n\n## Features\n\n- Pure Python.\n- Feature-rich yet lightweight. Even runs on MicroPython.\n- Supports struct-like format string, ctypes-like structure representation (i.e. `Structure._field_`) and dataclass-like message class as schema.\n- Support schema-less inspection of a given serialized message via `Wire.{encode,decode}_raw` API.\n  - Proudly doing this earlier than [protoscope](https://github.com/protocolbuffers/protoscope).\n\n## Getting started\n\nMiniPB supports 3 different flavors of schema declaration methods: Message classes (object serialization), key-value schema (dict serialization) and format string (tuple serialization).\n\n### Message class\n\n```python\nimport minipb\n\n### Encode/Decode a Message with schema defined via Fields\n@minipb.process_message_fields\nclass HelloWorldMessage(minipb.Message):\n    msg = minipb.Field(1, minipb.TYPE_STRING)\n\n# Creating a Message instance\n#   Method 1: init with kwargs work!\nmsg_obj = HelloWorldMessage(msg='Hello world!')\n\n#   Method 2: from_dict, iterates over all Field's declared in order on the class\nmsg_obj = HelloWorldMessage.from_dict({'msg': 'Hello world!'})\n\n# Encode a message\nencoded_msg = msg_obj.encode()\n# encoded_message == b'\\n\\x0cHello world!'\n\n# Decode a message\ndecoded_msg_obj = HelloWorldMessage.decode(encoded_msg)\n# decoded_msg == HelloWorldMessage(msg='Hello world!')\n\ndecoded_dict = decoded_msg_obj.to_dict()\n# decoded_dict == {'msg': 'Hello world!'}\n```\n\n### Key-value schema\n\n```python\nimport minipb\n\n### Encode/Decode a message with the Wire object and Key-Value Schema\n# Create the Wire object with schema\nhello_world_msg = minipb.Wire([\n    ('msg', 'U') # 'U' means UTF-8 string.\n])\n\n# Encode a message\nencoded_msg = hello_world_msg.encode({\n    'msg': 'Hello world!'\n})\n# encoded_message == b'\\n\\x0cHello world!'\n\n# Decode a message\ndecoded_msg = hello_world_msg.decode(encoded_msg)\n# decoded_msg == {'msg': 'Hello world!'}\n```\n\n### Format string\n\n```python\nimport minipb\n\n### Encode/Decode a message with the Wire object and Format String\nhello_world_msg = minipb.Wire('U')\n\n# Encode a message\nencoded_msg = hello_world_msg.encode('Hello world!')\n# encoded_message == b'\\n\\x0cHello world!'\n\n# Decode a message\ndecoded_msg = hello_world_msg.decode(encoded_msg)\n# decoded_msg == ('Hello world!',)\n```\n\nRefer to the [Schema Representation][schema] for detailed explanation on schema formats accepted by MiniPB.\n\n## Installation\n\n### CPython, PyPy, etc.\n\nInstall via pip\n\n```sh\npip install git+https://github.com/dogtopus/minipb\n```\n\n### MicroPython\n\n**NOTE (Old data but still somewhat relevant)**: Despite being lightweight compared to official Protobuf, the `minipb` module itself still uses around 15KB of RAM after loaded via `import`. Therefore it is recommended to use MiniPB on MicroPython instances with minimum of 24KB of memory available to the scripts. Instances with at least 48KB of free memory is recommended for more complex program logic.\n\nOn targets with plenty of RAM, such as Pyboards and the Unix build, installation consists of copying `minipb.py` to the filesystem and installing the `logging` and `bisect` module from [micropython-lib][mpylib]. For targets with restricted RAM there are two options: cross compilation and frozen bytecode. The latter offers the greatest saving. See the [official docs][mpydoc] for further explanation.\n\nCross compilation may be achieved as follows. First you need `mpy-cross` that is compatible with the mpy version you are using.\n\nCompile MiniPB by using\n\n```sh\nmpy-cross -s minipb.py minipb/minipb.py -o /your/PYBFLASH/minipb.mpy\n```\n\nYou also need `logging` and `bisect` module from [micropython-lib][mpylib]. Compile it by using\n\n```sh\nmpy-cross -s logging.py micropython-lib/logging/logging.py -o /your/PYBFLASH/logging.mpy\nmpy-cross -s bisect.py micropython-lib/bisect/bisect.py -o /your/PYBFLASH/bisect.mpy\n```\n\nUnmount PYBFLASH and reset the board when both files are installed to your MicroPython instance.\n\nOn production deployment, it is possible to run `mpy-cross` with `-O` set to higher than 0 to save more flash and RAM usage by sacrificing some debuggability. For example `-O3` saves about 1KB of flash and library RAM usage while disables assertion and removes source line numbers during traceback.\n\n```sh\nmpy-cross -s minipb.py -O3 minipb/minipb.py -o /your/PYBFLASH/minipb.mpy\nmpy-cross -s logging.py -O3 micropython-lib/logging/logging.py -o /your/PYBFLASH/logging.mpy\nmpy-cross -s bisect.py -O3 micropython-lib/bisect/bisect.py -o /your/PYBFLASH/bisect.mpy\n```\n\n## Usage\n\nDetailed documentation can be found under the project [Wiki][wiki]. The module's pydoc contains some useful information about the API too.\n\n[mpylib]: https://github.com/micropython/micropython-lib\n[wiki]: https://github.com/dogtopus/minipb/wiki\n[schema]: https://github.com/dogtopus/minipb/wiki/Schema-Representations\n[mpydoc]: http://docs.micropython.org/en/latest/reference/packages.html\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdogtopus%2Fminipb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdogtopus%2Fminipb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdogtopus%2Fminipb/lists"}