# Binary JData for Python - a lightweight binary JSON format
- Copyright: (C) Qianqian Fang (2020-2025) <q.fang at neu.edu>
- Copyright: (C) Iotic Labs Ltd. (2016-2019) <vilnis.termanis at iotic-labs.com>
- License: Apache License, Version 2.0
- Version: 0.5.4
- URL: https://pypi.org/project/bjdata/
- Github: https://github.com/NeuroJSON/pybj
- BJData Spec Version: [V1 Draft 3](https://neurojson.org/bjdata/draft3)
- Acknowledgement: This project is supported by US National Institute of Health (NIH) grant U24-NS124027
This is a Python v3.2+ (and 2.7+) [Binary JData](https://neurojson.org) encoder
and decoder based on the [Draft-3](Binary_JData_Specification.md) specification.
## Installing / packaging
```shell
## To get from PyPI
pip3 install bjdata
```
Other instalation options
```shell
## Installing / packaging
## To get from PyPI without root/administrator privilege
pip3 install bjdata --user
## To get from PyPI via python
python3 -mpip install bjdata
## To only build extension modules in-place (e.g. in repository)
python3 setup.py build_ext -i
## To build & install globally
python3 setup.py install
## To skip building of extensions when installing (or building)
PYBJDATA_NO_EXTENSION=1 python3 setup.py install
```
This package can be directly installed on Debian Bullseye/Ubuntu 21.04 or newer via
```
sudo apt-get install python3-bjdata
```
Both `python-bjdata` (for Python 2.7+) and `python3-bjdata` (for Python 3.x) can
also be installed on Ubuntu via
```
sudo add-apt-repository ppa:fangq/ppa
sudo apt-get update
sudo apt-get install python-bjdata python3-bjdata
```
**Notes**
- The extension module is not required but provide a significant speed boost.
- The above can also be run with v2.7+ (replacing `pip3` and `python3` above by `pip` and `python`, respectively)
- At run time, one can check whether compiled version is in use via the
`bjdata.EXTENSION_ENABLED` boolean
## Usage
It's meant to behave very much like Python's built-in
[JSON module](https://docs.python.org/3/library/json.html), e.g.:
```python
import bjdata as bj
obj={'a':123,'b':12.3,'c':[1,2,3,[4,5],'test']}
encoded = bj.dumpb(obj)
decoded = bj.loadb(encoded)
```
**Note**: Only unicode strings in Python 2 will be encoded as strings, plain *str*
will be encoded as a byte array.
## Documentation
```python
import bjdata as bj
help(bj.dump)
help(bj.load)
help(bj.encoder.dump)
help(bj.decoder.load)
```
## Command-line utility
This converts between JSON and BJData formats:
```shell
python3 -mbjdata
USAGE: bjdata (fromjson|tojson) (INFILE|-) [OUTFILE]
EXAMPLES:
python3 -mbjdata fromjson input.json output.bjd
python3 -mbjdata tojson input.bjd output.json
```
## Tests
### Static
This library has been checked using [flake8](https://pypi.python.org/pypi/flake8)
and [pylint](http://www.pylint.org), using a modified configuration -
see _pylint.rc_ and _flake8.cfg_.
### Unit
```shell
python3 -mvenv py
. py/bin/activate
pip install -U pip setuptools
pip install -e .[dev]
./coverage_test.sh
```
**Note**: See `coverage_test.sh` for additional requirements.
## Limitations
- The **No-Op** type is only supported by the decoder. (This should arguably be
a protocol-level rather than serialisation-level option.) Specifically, it is
**only** allowed to occur at the start or between elements of a container and
**only** inside un-typed containers. (In a typed container it is impossible to
tell the difference between an encoded element and a No-Op.)
- Strongly-typed containers are only supported by the decoder (apart from for
**bytes**/**bytearray**) and not for No-Op.
- Encoder/decoder extensions are not supported at this time.
- Encoder/decoder only support numpy NDarrays and scalars, other numpy types are not supported.
## Acknowledgement
This package was modified based on the py-ubjson package developed by
[Iotic Labs Ltd.](https://www.iotics.com/)
Project URL: https://github.com/Iotic-Labs/py-ubjson
The major changes were focused on supporting the Binary JData Specification
[Draft 3](https://neurojson.org/bjdata/draft3) -
an extended Universal Binary JSON (UBJSON) Specification Draft-12 by adding
the below new features:
* BJData adds 5 new data types: `uint16 [u]`, `uint32 [m]`, `uint64 [M]`, `float16 [h]`, and `byte [B]`
* BJData adds a dedicated byte data type used in optimized array containers for binary data
* BJData supports an optimized ND array container
* BJData does not convert NaN/Inf/-Inf to `null`
* BJData uses little-Endian as the default integer/floating-point numbers while UBJSON uses big-Endian
* BJData only permits non-zero-fixed-length data types (`UiuImlMLhdDCB`) in strongly-typed array/object containers
Raw data
{
"_id": null,
"home_page": "https://github.com/NeuroJSON/pybj",
"name": "bjdata",
"maintainer": "Qianqian Fang",
"docs_url": null,
"requires_python": null,
"maintainer_email": "fangqq@gmail.com",
"keywords": "JSON, JData, UBJSON, BJData, OpenJData, NeuroJSON, JNIfTI, Encoder, Decoder",
"author": "Qianqian Fang",
"author_email": "fangqq@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/e6/92/350d5e0a75a4f58d2dffc8864faf53c0284fa569ff48443713f2c4bd2850/bjdata-0.5.4.tar.gz",
"platform": null,
"description": "\n\n# Binary JData for Python - a lightweight binary JSON format\n\n- Copyright: (C) Qianqian Fang (2020-2025) <q.fang at neu.edu>\n- Copyright: (C) Iotic Labs Ltd. (2016-2019) <vilnis.termanis at iotic-labs.com>\n- License: Apache License, Version 2.0\n- Version: 0.5.4\n- URL: https://pypi.org/project/bjdata/\n- Github: https://github.com/NeuroJSON/pybj\n- BJData Spec Version: [V1 Draft 3](https://neurojson.org/bjdata/draft3)\n- Acknowledgement: This project is supported by US National Institute of Health (NIH) grant U24-NS124027\n\n\n\nThis is a Python v3.2+ (and 2.7+) [Binary JData](https://neurojson.org) encoder\nand decoder based on the [Draft-3](Binary_JData_Specification.md) specification.\n\n## Installing / packaging\n```shell\n## To get from PyPI\npip3 install bjdata\n```\n\nOther instalation options\n```shell\n## Installing / packaging\n\n## To get from PyPI without root/administrator privilege\npip3 install bjdata --user\n\n## To get from PyPI via python\npython3 -mpip install bjdata\n\n## To only build extension modules in-place (e.g. in repository)\npython3 setup.py build_ext -i\n\n## To build & install globally\npython3 setup.py install\n\n## To skip building of extensions when installing (or building)\nPYBJDATA_NO_EXTENSION=1 python3 setup.py install\n```\n\nThis package can be directly installed on Debian Bullseye/Ubuntu 21.04 or newer via\n```\nsudo apt-get install python3-bjdata\n```\n\nBoth `python-bjdata` (for Python 2.7+) and `python3-bjdata` (for Python 3.x) can \nalso be installed on Ubuntu via\n```\nsudo add-apt-repository ppa:fangq/ppa\nsudo apt-get update\nsudo apt-get install python-bjdata python3-bjdata\n```\n\n**Notes**\n\n- The extension module is not required but provide a significant speed boost.\n- The above can also be run with v2.7+ (replacing `pip3` and `python3` above by `pip` and `python`, respectively)\n- At run time, one can check whether compiled version is in use via the \n`bjdata.EXTENSION_ENABLED` boolean\n\n\n## Usage\nIt's meant to behave very much like Python's built-in \n[JSON module](https://docs.python.org/3/library/json.html), e.g.:\n```python\nimport bjdata as bj\n\nobj={'a':123,'b':12.3,'c':[1,2,3,[4,5],'test']}\nencoded = bj.dumpb(obj)\ndecoded = bj.loadb(encoded)\n```\n**Note**: Only unicode strings in Python 2 will be encoded as strings, plain *str* \nwill be encoded as a byte array.\n\n\n## Documentation\n```python\nimport bjdata as bj\nhelp(bj.dump)\nhelp(bj.load)\nhelp(bj.encoder.dump)\nhelp(bj.decoder.load)\n```\n\n## Command-line utility\nThis converts between JSON and BJData formats:\n```shell\npython3 -mbjdata\nUSAGE: bjdata (fromjson|tojson) (INFILE|-) [OUTFILE]\n\nEXAMPLES:\n\npython3 -mbjdata fromjson input.json output.bjd\npython3 -mbjdata tojson input.bjd output.json\n```\n\n\n## Tests\n\n### Static\nThis library has been checked using [flake8](https://pypi.python.org/pypi/flake8) \nand [pylint](http://www.pylint.org), using a modified configuration - \nsee _pylint.rc_ and _flake8.cfg_.\n\n### Unit\n```shell\npython3 -mvenv py\n. py/bin/activate\npip install -U pip setuptools\npip install -e .[dev]\n\n./coverage_test.sh\n```\n**Note**: See `coverage_test.sh` for additional requirements.\n\n\n## Limitations\n- The **No-Op** type is only supported by the decoder. (This should arguably be \n a protocol-level rather than serialisation-level option.) Specifically, it is \n **only** allowed to occur at the start or between elements of a container and \n **only** inside un-typed containers. (In a typed container it is impossible to \n tell the difference between an encoded element and a No-Op.)\n- Strongly-typed containers are only supported by the decoder (apart from for \n **bytes**/**bytearray**) and not for No-Op.\n- Encoder/decoder extensions are not supported at this time.\n- Encoder/decoder only support numpy NDarrays and scalars, other numpy types are not supported.\n\n\n## Acknowledgement\n\nThis package was modified based on the py-ubjson package developed by\n[Iotic Labs Ltd.](https://www.iotics.com/) \nProject URL: https://github.com/Iotic-Labs/py-ubjson\n\nThe major changes were focused on supporting the Binary JData Specification \n[Draft 3](https://neurojson.org/bjdata/draft3) -\nan extended Universal Binary JSON (UBJSON) Specification Draft-12 by adding\nthe below new features:\n\n* BJData adds 5 new data types: `uint16 [u]`, `uint32 [m]`, `uint64 [M]`, `float16 [h]`, and `byte [B]`\n* BJData adds a dedicated byte data type used in optimized array containers for binary data\n* BJData supports an optimized ND array container\n* BJData does not convert NaN/Inf/-Inf to `null`\n* BJData uses little-Endian as the default integer/floating-point numbers while UBJSON uses big-Endian\n* BJData only permits non-zero-fixed-length data types (`UiuImlMLhdDCB`) in strongly-typed array/object containers\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Binary JData and UBJSON encoder/decoder",
"version": "0.5.4",
"project_urls": {
"Homepage": "https://github.com/NeuroJSON/pybj"
},
"split_keywords": [
"json",
" jdata",
" ubjson",
" bjdata",
" openjdata",
" neurojson",
" jnifti",
" encoder",
" decoder"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e692350d5e0a75a4f58d2dffc8864faf53c0284fa569ff48443713f2c4bd2850",
"md5": "0063caa73cef83966e31e79460899796",
"sha256": "5001a70d0f6cd7fa22447c208c8780aa55c343bb33ad901bdf5da389bcedcca1"
},
"downloads": -1,
"filename": "bjdata-0.5.4.tar.gz",
"has_sig": false,
"md5_digest": "0063caa73cef83966e31e79460899796",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 67545,
"upload_time": "2025-07-28T04:50:44",
"upload_time_iso_8601": "2025-07-28T04:50:44.987551Z",
"url": "https://files.pythonhosted.org/packages/e6/92/350d5e0a75a4f58d2dffc8864faf53c0284fa569ff48443713f2c4bd2850/bjdata-0.5.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-28 04:50:44",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NeuroJSON",
"github_project": "pybj",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "bjdata"
}
JSON
