# Hiss Byte Notation
Library to make it easy to use python literal syntax as a data format
Have you seen people try to print a dict and then use the JSON library to parse the output? This library is some
helper function for that scenario. It is a small wrapper around ast.literal_eval and will have a API similar to other
serializer/deserializers such as json, pickle, pyyaml, etc.
## Safety
`ast.literal_eval` is safer than `eval` but the python docs still imply that there are malicious payloads. I'm not
sure if they are the same problems that could affect json or other formats.
## Usage
```python
import hissbytenotation as hbn
data = {
"mammal": "cat",
"reptile": ["snake", "lizard"],
"version": 1
}
data_as_string = hbn.dumps(data)
rehydrated = hbn.loads(data_as_string)
print(rehydrated)
# {'mammal': 'cat', 'reptile': ['snake', 'lizard'], 'version': 1}
```
## How it works
Serialization is done by calling repr, checking if ast.literal_eval can read it. Repr can be called on more data
structures than ast.literal_eval can handle.
Because ast.literal_eval is so slow, there are other options for deserialization:
- default: ast.literal_eval with validation enabled. Very slow, very safe.
- eval. Slow, only for trusted data.
- exec. Slow, only for trusted data.
- import. Two times faster than exec, only for trusted data.
## Serialization and deserialization times for 10,000 dumps/loads
Pickle: 0.89 seconds
JSON: 2.00 seconds
HBN (no validation): 20.80 seconds
HBN (validation): 40.57 seconds
HBN (unsafe): 15.95 seconds
HBN (exec): 18.08 seconds
HBN (by import): 12.26 seconds
## Prior art
- [literal-python-to-pickle](https://github.com/albertz/literal-python-to-pickle) A faster replacement for
ast.literal_eval and
corresponding [question on stackoverflow](https://stackoverflow.com/questions/66480073/fastest-implementation-of-ast-literal-eval).
- You could just call `repr` and `ast.literal_eval` directly.
Possibly [astor](https://pypi.org/project/astor/) which serializes to a string representation of the AST, which looks
nothing like the source code, nor json.
Raw data
{
"_id": null,
"home_page": "https://github.com/matthewdeanmartin/hissbytenotation",
"name": "hissbytenotation",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "serializer,deserializer,hbn",
"author": "Matthew Martin",
"author_email": "matthewdeanmartin@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e5/e3/e50af7af1e77ae6c6063194029ccf3af60df631b1f7030eb8e4db38cd6d7/hissbytenotation-0.2.0.tar.gz",
"platform": null,
"description": "# Hiss Byte Notation\n\nLibrary to make it easy to use python literal syntax as a data format\n\nHave you seen people try to print a dict and then use the JSON library to parse the output? This library is some\nhelper function for that scenario. It is a small wrapper around ast.literal_eval and will have a API similar to other\nserializer/deserializers such as json, pickle, pyyaml, etc.\n\n## Safety\n\n`ast.literal_eval` is safer than `eval` but the python docs still imply that there are malicious payloads. I'm not\nsure if they are the same problems that could affect json or other formats.\n\n## Usage\n\n```python\nimport hissbytenotation as hbn\n\ndata = {\n \"mammal\": \"cat\",\n \"reptile\": [\"snake\", \"lizard\"],\n \"version\": 1\n}\ndata_as_string = hbn.dumps(data)\n\nrehydrated = hbn.loads(data_as_string)\nprint(rehydrated)\n# {'mammal': 'cat', 'reptile': ['snake', 'lizard'], 'version': 1}\n```\n\n## How it works\n\nSerialization is done by calling repr, checking if ast.literal_eval can read it. Repr can be called on more data\nstructures than ast.literal_eval can handle.\n\nBecause ast.literal_eval is so slow, there are other options for deserialization:\n\n- default: ast.literal_eval with validation enabled. Very slow, very safe.\n- eval. Slow, only for trusted data.\n- exec. Slow, only for trusted data.\n- import. Two times faster than exec, only for trusted data.\n\n## Serialization and deserialization times for 10,000 dumps/loads\n\n Pickle: 0.89 seconds\n JSON: 2.00 seconds\n HBN (no validation): 20.80 seconds\n HBN (validation): 40.57 seconds\n HBN (unsafe): 15.95 seconds\n HBN (exec): 18.08 seconds\n HBN (by import): 12.26 seconds\n\n## Prior art\n\n- [literal-python-to-pickle](https://github.com/albertz/literal-python-to-pickle) A faster replacement for\n ast.literal_eval and\n corresponding [question on stackoverflow](https://stackoverflow.com/questions/66480073/fastest-implementation-of-ast-literal-eval).\n\n- You could just call `repr` and `ast.literal_eval` directly.\n\nPossibly [astor](https://pypi.org/project/astor/) which serializes to a string representation of the AST, which looks\nnothing like the source code, nor json.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Serialize and deserialize data to python source notation (hbn)",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/matthewdeanmartin/hissbytenotation/issues",
"Change Log": "https://github.com/matthewdeanmartin/hissbytenotation/blob/main/CHANGES.md",
"Documentation": "https://github.com/matthewdeanmartin/hissbytenotation",
"Homepage": "https://github.com/matthewdeanmartin/hissbytenotation",
"Repository": "https://github.com/matthewdeanmartin/hissbytenotation"
},
"split_keywords": [
"serializer",
"deserializer",
"hbn"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a95a626f46d664637699bf3d04305d422a95fa0b12d346634c7c96c6eb1cdc6f",
"md5": "23a0e2341201fc0e8ee35eee4bff46a2",
"sha256": "7d85ad4f0b9587b256818c0c5f8da14d60306a78577419eedc064fce5a1000da"
},
"downloads": -1,
"filename": "hissbytenotation-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "23a0e2341201fc0e8ee35eee4bff46a2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 5763,
"upload_time": "2023-08-12T17:33:15",
"upload_time_iso_8601": "2023-08-12T17:33:15.786562Z",
"url": "https://files.pythonhosted.org/packages/a9/5a/626f46d664637699bf3d04305d422a95fa0b12d346634c7c96c6eb1cdc6f/hissbytenotation-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "e5e3e50af7af1e77ae6c6063194029ccf3af60df631b1f7030eb8e4db38cd6d7",
"md5": "d0813186fc304f997375b0bff8addda7",
"sha256": "34787e8119526374bd75bce45766939f816f23a2fac3b1d027c21cbadd31b104"
},
"downloads": -1,
"filename": "hissbytenotation-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "d0813186fc304f997375b0bff8addda7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 5432,
"upload_time": "2023-08-12T17:33:17",
"upload_time_iso_8601": "2023-08-12T17:33:17.157487Z",
"url": "https://files.pythonhosted.org/packages/e5/e3/e50af7af1e77ae6c6063194029ccf3af60df631b1f7030eb8e4db38cd6d7/hissbytenotation-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-12 17:33:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "matthewdeanmartin",
"github_project": "hissbytenotation",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "hissbytenotation"
}
JSON
