| Name | humon JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | A python wrapper for the Humon C API. |
| upload_time | 2024-06-04 19:26:20 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | MIT License |
| keywords |
humon
c
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# humon
A Python wrapper for the Humon C API. This project uses Cython, so can theoretically be used wherever Cython modules can be used.
## Installation
Thus far, the Python wrapper has only been tested on Linux-like systems. Available as a PyPI package:
```
$ pip install humon
```
Or, you can clone it from github:
```
$ git clone https://github.com/spacemeat/humon-cy
$ pip install ./humon-cy
```
It's best practice to emplace it in a virtual environment.
## API overview
See the [Humon project readme](https://github.com/spacemeat/humon) for comprehensive details about Humon's format. This readme only describes the Python interface. The API is not strictly 1-1 with the C/C++ APIs.
### Loading troves
Easy. There are two ways:
```python
import humon as h
eqipment_trove = h.from_file('equipment.hu') # default encoding = h.Encoding.UNKNOWN
quests_trove = h.from_file('equipment.hu', h.Encoding.UTF8)
```
```python
import humon as h
trove = h.from_string('{foo: bar}')
```
The file on disk may be encoded with any UTF-n format, as in the C API. Python strings are already Unicode-encoded, and will be converted to UTF-8 (Humon's internal format) if need be.
The returned `trove` is the container for the Humon data. It will hold the entire file or string, and provide very quick access to the contents for reading once loaded. Troves are immutable once created.
> Both functions also take an optional parameter `tab_size: int`. This is to help error diagnostics determine the correct column.
### Accessing nodes
For much of the rest of this document, we'll utilize a sample Humon file on disk:
```
$ cat gnome.hu
@ { app: gamin'-djinn, component: assets-gnome, version: 0.1.0 }
{
model: gnome-generic.fbx
textures: [
gnome-generic-albedo.png
gnome-generic-bump.png @ units: model-space
gnome-generic-metallic.png
]
animations: {
idle: [
gnome-idle_0.anim
gnome-idle_1.anim
]
}
}
```
Humon data is a tree of nodes: lists, dicts, and values, organized like JSON data. There are also comments and annotations, and all of this is described in the [Humon project readme](https://github.com/spacemeat/humon). Currently, comments cannot be accessed through the API, though that is forthcoming.
Getting the root node is done through the `root` property of a trove:
```python
import humon as h
trove = h.from_string('{foo: [a b c d]}')
root = trove.root
```
The returned object is of type `Node`. You can access its kind--list, dict, value--by the `kind` property. A list or dict will have child nodes, accessible through __getitem__(). Any child of a dict will have a `key` property. A value node will have a `value` property.
```python
import humon as h
trove = h.from_string('{foo: [a b c d]}')
root = trove.root
assert root.kind == NodeKind.DICT
lnode = root['foo']
vnode = lnode[2]
print (vnode.value) # prints: c
```
A minor difference between Humon and JSON is that Humon dict entries can be accessed by index as well, and keep their order as loaded. (This is a strict language feature, and not dependent on any API.)
```python
import humon as h
trove = h.from_string('{foo: foofoo, bar: barbar, baz: bazbaz}')
vnode = trove.root[2]
print (vnode.value) # prints bazbaz
```
Another minor difference between Humon and JSON is that Humon dicts do not have to have unique keys. You can access the nth child node with a given key:
```python
import humon as h
trove = h.from_string('''{ foo: [a b c d]
bar: snaa
foo: [e f g h]
baz: plugh
foo: [i j k l] }''')
vnode = trove.root['foo', 2]
print (f'{vnode.address}: {vnode.value}') # prints: /foo: [i j k l]
```
You can also access nodes via address:
```python
import humon as h
trove = h.from_string('{foo: [a b c d]}')
vnode = trove.get_node('/foo/2')
print (f'{vnode.address}: {vnode.value}') # prints: /foo/2: c
vnode = vnode.get_node('../3')
print (f'{vnode.address}: {vnode.value}') # prints: /foo/3: d
```
Nodes which share a parent are `sibling` nodes:
```python
import humon as h
trove = h.from_string('{foo: [a b c d] bar: [e f g h]}')
vnode = trove.get_node('/foo')
print (f'{vnode.address}: {vnode.value}') # prints: /foo: [a b c d]
vnode = vnode.get_sibling('bar')
print (f'{vnode.address}: {vnode.value}') # prints: /bar: [e f g h]
vnode = vnode[0].sibling()
print (f'{vnode.address}: {vnode.value}') # prints: /bar/0: e
```
A trove stores nodes as a linear array internally, and nodes can be accessed by index from the Trove ojbect:
```python
import humon as h
trove = h.from_string('{foo: [a b c d]}')
print (trove.get_node(4).value) # prints: c
```
### Annotations
Annotations on a trove or node are returned as dicts. Assuming a reasonable implementation of a Version class:
```python
import humon as h
data = '''@ { app: gamin'-djinn, component: assets-gnome, version: 0.1.0 }
{
model: gnome-generic.fbx
textures: [
gnome-generic-albedo.png
gnome-generic-bump.png @ units: model-space
gnome-generic-metallic.png
]
animations: {
idle: [
gnome-idle_0.anim
gnome-idle_1.anim
]
}
}'''
trove = h.from_string(data)
to = trove.annotations
assert to['app'] == "gamin'-djinn"
if Version(to['version']).in_range('0.0.4', '0.1.3'):
print (trove.get_node('/textures/1').annotations) # prints: {'units': 'model-space'}
```
### Serializing
Though a trove is immutable, it can be printed in a few ways. The most useful maybe is with Trove.to_string() and Trove.to_file():
```python
...
s = trove.to_string(h.WhitespaceFormat.MINIMAL, print_comments = False)
```
The minimal formatting reduces the whitespace to a minimum while keeping Humon semantics the same. You can do a pretty formatting as well:
```python
...
trove.to_file(path: 'pretty.h',
whitespace_format = h.WhitespaceFormat.PRETTY, indent_size = 4,
indent_with_tabs = False, use_colors = True, color_table = None,
print_comments = True, newline = '\n', print_bom = True)
```
Passing `True` to `use_colors` will insert colorizing markup entries appropriately in the resutlant string. If you specify `use_colors`, but do not provide a color table, the API will use some ANSI color codes as default values. Set color entries for each color type like so:
```python
...
named_fg = {
'black': '\033[30m',
'red': '\033[31m',
'green': '\033[32m',
'yellow': '\033[33m',
'blue': '\033[34m',
'magenta': '\033[35m',
'cyan': '\033[36m',
'white': '\033[37m',
'bright black': '\033[90m',
'bright red': '\033[91m',
'bright green': '\033[92m',
'bright yellow': '\033[93m',
'bright blue': '\033[94m',
'bright magenta': '\033[95m',
'bright cyan': '\033[96m',
'bright white': '\033[97m',
}
color_table = {
h.ColorCode.TOKENSTREAMBEGIN: '',
h.ColorCode.TOKENSTREAMEND: '\033[0m',
h.ColorCode.TOKENEND: '',
h.ColorCode.PUNCLIST: named_fg['bright white'],
h.ColorCode.PUNCDICT: named_fg['bright white'],
h.ColorCode.PUNCKEYVALUESEP: named_fg['bright white'],
h.ColorCode.PUNCANNOTATE: named_fg['bright blue'],
h.ColorCode.PUNCANNOTATEDICT: named_fg['bright blue'],
h.ColorCode.PUNCANNOTATEKEYVALUESEP: named_fg['blue'],
h.ColorCode.KEY: named_fg['cyan'],
h.ColorCode.VALUE: named_fg['bright cyan'],
h.ColorCode.COMMENT: named_fg['red'],
h.ColorCode.ANNOKEY: named_fg['magenta'],
h.ColorCode.ANNOVALUE: named_fg['bright magenta'],
h.ColorCode.WHITESPACE: named_fg['white'],
}
trove.to_file(path: 'pretty.h',
whitespace_format = h.WhitespaceFormat.PRETTY, indent_size = 4,
indent_with_tabs = False, use_colors = True, color_table = color_table,
print_comments = True, newline = '\n', print_bom = True)
```
You can also access full text in a node or trove with `token_string`:
```python
import humon as h
trove = h.from_string('{foo: [a b {color: {green: [froggy, leafy]}} d]}')
print (trove.get_node('/foo/2').token_string) # prints: {green: [froggy, leafy]}}
print (trove.token_string) # prints the whole trove
```
> Calling `token_string` on the trove is nearly equivalent to calling 'Trove.to_string' with `whitespace_format` set to `humon.WhitespaceFormat.CLONED` and no colors. But, since it copies directly from the loaded text, it is much faster.
Raw data
{
"_id": null,
"home_page": null,
"name": "humon",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": "Trevor Schrock <spacemeat@gmail.com>",
"keywords": "Humon, C",
"author": null,
"author_email": "Trevor Schrock <spacemeat@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/86/bf/155ca0a354b2c216fdf60ade895437d8428a88d9268cacd9754ba1b997d9/humon-0.1.0.tar.gz",
"platform": null,
"description": "# humon\n\nA Python wrapper for the Humon C API. This project uses Cython, so can theoretically be used wherever Cython modules can be used.\n\n## Installation\n\nThus far, the Python wrapper has only been tested on Linux-like systems. Available as a PyPI package:\n\n```\n$ pip install humon\n```\n\nOr, you can clone it from github:\n\n```\n$ git clone https://github.com/spacemeat/humon-cy\n$ pip install ./humon-cy\n```\n\nIt's best practice to emplace it in a virtual environment.\n\n## API overview\n\nSee the [Humon project readme](https://github.com/spacemeat/humon) for comprehensive details about Humon's format. This readme only describes the Python interface. The API is not strictly 1-1 with the C/C++ APIs.\n\n### Loading troves\n\nEasy. There are two ways:\n\n```python\nimport humon as h\neqipment_trove = h.from_file('equipment.hu') # default encoding = h.Encoding.UNKNOWN\nquests_trove = h.from_file('equipment.hu', h.Encoding.UTF8)\n```\n\n```python\nimport humon as h\ntrove = h.from_string('{foo: bar}')\n```\n\nThe file on disk may be encoded with any UTF-n format, as in the C API. Python strings are already Unicode-encoded, and will be converted to UTF-8 (Humon's internal format) if need be.\n\nThe returned `trove` is the container for the Humon data. It will hold the entire file or string, and provide very quick access to the contents for reading once loaded. Troves are immutable once created.\n\n> Both functions also take an optional parameter `tab_size: int`. This is to help error diagnostics determine the correct column.\n\n### Accessing nodes\n\nFor much of the rest of this document, we'll utilize a sample Humon file on disk:\n\n```\n$ cat gnome.hu\n@ { app: gamin'-djinn, component: assets-gnome, version: 0.1.0 }\n{\n model: gnome-generic.fbx\n textures: [\n gnome-generic-albedo.png\n gnome-generic-bump.png @ units: model-space\n gnome-generic-metallic.png\n ]\n animations: {\n idle: [\n gnome-idle_0.anim\n gnome-idle_1.anim\n ]\n }\n}\n```\n\nHumon data is a tree of nodes: lists, dicts, and values, organized like JSON data. There are also comments and annotations, and all of this is described in the [Humon project readme](https://github.com/spacemeat/humon). Currently, comments cannot be accessed through the API, though that is forthcoming.\n\nGetting the root node is done through the `root` property of a trove:\n\n```python\nimport humon as h\ntrove = h.from_string('{foo: [a b c d]}')\nroot = trove.root\n```\n\nThe returned object is of type `Node`. You can access its kind--list, dict, value--by the `kind` property. A list or dict will have child nodes, accessible through __getitem__(). Any child of a dict will have a `key` property. A value node will have a `value` property.\n\n```python\nimport humon as h\ntrove = h.from_string('{foo: [a b c d]}')\nroot = trove.root\nassert root.kind == NodeKind.DICT\nlnode = root['foo']\nvnode = lnode[2]\nprint (vnode.value) # prints: c\n```\n\nA minor difference between Humon and JSON is that Humon dict entries can be accessed by index as well, and keep their order as loaded. (This is a strict language feature, and not dependent on any API.)\n\n```python\nimport humon as h\ntrove = h.from_string('{foo: foofoo, bar: barbar, baz: bazbaz}')\nvnode = trove.root[2]\nprint (vnode.value) # prints bazbaz\n```\n\nAnother minor difference between Humon and JSON is that Humon dicts do not have to have unique keys. You can access the nth child node with a given key:\n\n```python\nimport humon as h\ntrove = h.from_string('''{ foo: [a b c d]\n bar: snaa\n foo: [e f g h]\n baz: plugh\n foo: [i j k l] }''')\nvnode = trove.root['foo', 2]\nprint (f'{vnode.address}: {vnode.value}') # prints: /foo: [i j k l]\n```\n\nYou can also access nodes via address:\n\n```python\nimport humon as h\ntrove = h.from_string('{foo: [a b c d]}')\nvnode = trove.get_node('/foo/2')\nprint (f'{vnode.address}: {vnode.value}') # prints: /foo/2: c\nvnode = vnode.get_node('../3')\nprint (f'{vnode.address}: {vnode.value}') # prints: /foo/3: d\n```\n\nNodes which share a parent are `sibling` nodes:\n\n```python\nimport humon as h\ntrove = h.from_string('{foo: [a b c d] bar: [e f g h]}')\nvnode = trove.get_node('/foo')\nprint (f'{vnode.address}: {vnode.value}') # prints: /foo: [a b c d]\nvnode = vnode.get_sibling('bar')\nprint (f'{vnode.address}: {vnode.value}') # prints: /bar: [e f g h]\nvnode = vnode[0].sibling()\nprint (f'{vnode.address}: {vnode.value}') # prints: /bar/0: e\n```\n\nA trove stores nodes as a linear array internally, and nodes can be accessed by index from the Trove ojbect:\n\n```python\nimport humon as h\ntrove = h.from_string('{foo: [a b c d]}')\nprint (trove.get_node(4).value) # prints: c\n```\n\n### Annotations\n\nAnnotations on a trove or node are returned as dicts. Assuming a reasonable implementation of a Version class:\n\n```python\nimport humon as h\n\ndata = '''@ { app: gamin'-djinn, component: assets-gnome, version: 0.1.0 }\n{\n model: gnome-generic.fbx\n textures: [\n gnome-generic-albedo.png\n gnome-generic-bump.png @ units: model-space\n gnome-generic-metallic.png\n ]\n animations: {\n idle: [\n gnome-idle_0.anim\n gnome-idle_1.anim\n ]\n }\n}'''\n\ntrove = h.from_string(data)\nto = trove.annotations\nassert to['app'] == \"gamin'-djinn\"\nif Version(to['version']).in_range('0.0.4', '0.1.3'):\n print (trove.get_node('/textures/1').annotations) # prints: {'units': 'model-space'}\n```\n\n### Serializing\n\nThough a trove is immutable, it can be printed in a few ways. The most useful maybe is with Trove.to_string() and Trove.to_file():\n\n```python\n...\ns = trove.to_string(h.WhitespaceFormat.MINIMAL, print_comments = False)\n```\n\nThe minimal formatting reduces the whitespace to a minimum while keeping Humon semantics the same. You can do a pretty formatting as well:\n\n```python\n...\ntrove.to_file(path: 'pretty.h',\n whitespace_format = h.WhitespaceFormat.PRETTY, indent_size = 4,\n indent_with_tabs = False, use_colors = True, color_table = None, \n print_comments = True, newline = '\\n', print_bom = True)\n```\n\nPassing `True` to `use_colors` will insert colorizing markup entries appropriately in the resutlant string. If you specify `use_colors`, but do not provide a color table, the API will use some ANSI color codes as default values. Set color entries for each color type like so:\n\n```python\n...\nnamed_fg = {\n 'black': '\\033[30m',\n 'red': '\\033[31m',\n 'green': '\\033[32m',\n 'yellow': '\\033[33m',\n 'blue': '\\033[34m',\n 'magenta': '\\033[35m',\n 'cyan': '\\033[36m',\n 'white': '\\033[37m',\n\n 'bright black': '\\033[90m',\n 'bright red': '\\033[91m',\n 'bright green': '\\033[92m',\n 'bright yellow': '\\033[93m',\n 'bright blue': '\\033[94m',\n 'bright magenta': '\\033[95m',\n 'bright cyan': '\\033[96m',\n 'bright white': '\\033[97m',\n}\n\ncolor_table = {\n h.ColorCode.TOKENSTREAMBEGIN: '',\n h.ColorCode.TOKENSTREAMEND: '\\033[0m',\n h.ColorCode.TOKENEND: '',\n h.ColorCode.PUNCLIST: named_fg['bright white'],\n h.ColorCode.PUNCDICT: named_fg['bright white'],\n h.ColorCode.PUNCKEYVALUESEP: named_fg['bright white'],\n h.ColorCode.PUNCANNOTATE: named_fg['bright blue'],\n h.ColorCode.PUNCANNOTATEDICT: named_fg['bright blue'],\n h.ColorCode.PUNCANNOTATEKEYVALUESEP: named_fg['blue'],\n h.ColorCode.KEY: named_fg['cyan'],\n h.ColorCode.VALUE: named_fg['bright cyan'],\n h.ColorCode.COMMENT: named_fg['red'],\n h.ColorCode.ANNOKEY: named_fg['magenta'],\n h.ColorCode.ANNOVALUE: named_fg['bright magenta'],\n h.ColorCode.WHITESPACE: named_fg['white'],\n}\n\ntrove.to_file(path: 'pretty.h',\n whitespace_format = h.WhitespaceFormat.PRETTY, indent_size = 4,\n indent_with_tabs = False, use_colors = True, color_table = color_table,\n print_comments = True, newline = '\\n', print_bom = True)\n```\n\nYou can also access full text in a node or trove with `token_string`:\n\n```python\nimport humon as h\ntrove = h.from_string('{foo: [a b {color: {green: [froggy, leafy]}} d]}')\nprint (trove.get_node('/foo/2').token_string) # prints: {green: [froggy, leafy]}}\nprint (trove.token_string) # prints the whole trove\n```\n\n> Calling `token_string` on the trove is nearly equivalent to calling 'Trove.to_string' with `whitespace_format` set to `humon.WhitespaceFormat.CLONED` and no colors. But, since it copies directly from the loaded text, it is much faster.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "A python wrapper for the Humon C API.",
"version": "0.1.0",
"project_urls": {
"Repository": "https://github.com/spacemeat/humon-cy.git"
},
"split_keywords": [
"humon",
" c"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "86bf155ca0a354b2c216fdf60ade895437d8428a88d9268cacd9754ba1b997d9",
"md5": "417e347e0f104374cf6492df524ce7a9",
"sha256": "48db90b0031f395ad84280df45ba403bb6f21e969c5b4d7b7c1fa0efdbfe37eb"
},
"downloads": -1,
"filename": "humon-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "417e347e0f104374cf6492df524ce7a9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 181453,
"upload_time": "2024-06-04T19:26:20",
"upload_time_iso_8601": "2024-06-04T19:26:20.891855Z",
"url": "https://files.pythonhosted.org/packages/86/bf/155ca0a354b2c216fdf60ade895437d8428a88d9268cacd9754ba1b997d9/humon-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-06-04 19:26:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "spacemeat",
"github_project": "humon-cy",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "humon"
}
