dag-json

Python implementation of the IPLD DAG-JSON codec. Uses the CID class from multiformats. Passes all of IPLD's DAG-JSON cross-codec test fixtures.

Install from PyPI with pip install dag-json.

License: This project is placed in the public domain. You may also use it under the CC0 License.

• Usage
• Changelog
• Release instructions

Usage

The dag_json module has three functions:

• decode takes DAG-JSON encoded bytes and returns the corresponding native Python object.
• encode takes any IPLD-compatible native Python object - int, float, str, bool, list, bytes, or multiformats.CID - and returns it as DAG-JSON encoded bytes.
• encoded_cid takes DAG-JSON encoded bytes and returns its corresponding multiformats.CID.

Here's example usage:

>>> from dag_json import decode, encode, encoded_cid
>>> from multiformats import CID

>>> encoded = encode({
    'foo': 'bar',
    'data': b'hello world',
    'link': CID.decode('QmUGhP2X8xo9dsj45vqx1H6i5WqPqLqmLQsHTTxd3ke8mp'),
})
>>> encoded
b'{"data":{"/":{"bytes":"aGVsbG8gd29ybGQ"}},"foo":"bar","link":{"/":"QmUGhP2X8xo9dsj45vqx1H6i5WqPqLqmLQsHTTxd3ke8mp"}}'

>>> repr(decode(encoded))
{
    'data': b'hello world',
    'foo': 'bar',
    'link': CID('base58btc', 0, 'dag-pb', '12205822d187bd40b04cc8ae7437888ebf844efac1729e098c8816d585d0fcc42b5b'),
}

>>> encoded_cid(encoded)
CID('base58btc', 1, 'dag-json', '1220d7c1db350b6fda1df4ab788bffc87b24c68d05ddfb2c9ff6f2a4f9eb12236c31')

Changelog

0.3 - 2024-09-23

• Add new dialect kwarg to decode to match encode.

0.2 - 2024-06-24

• Add new encoded_cid function.
• Add new dialect kwarg to encode, DagJsonEncoder. Currently only supports one value, 'atproto', to encode CIDs and bytes with $link and $bytes keys according to the AT Protocol data model.

0.1 - 2023-04-23

Initial release!

Release instructions

Here's how to package, test, and ship a new release.

1. Run the unit tests.

   source local/bin/activate.csh
   python -m unittest discover
   

2. Bump the version number in pyproject.toml. git grep the old version number to make sure it only appears in the changelog. Change the current changelog entry in README.md for this new version from unreleased to the current date.

3. git commit -am 'release vX.Y'

4. Upload to test.pypi.org for testing.

   python -m build
   setenv ver X.Y
   twine upload -r pypitest dist/dag_json-$ver*
   

5. Install from test.pypi.org.

   cd /tmp
   python -m venv local
   source local/bin/activate.csh
   pip uninstall dag-json # make sure we force pip to use the uploaded version
   pip install --upgrade pip
   pip install -i https://test.pypi.org/simple --extra-index-url https://pypi.org/simple dag-json==$ver
   

6. Run the example code above to test that the code loads and runs.

7. Tag the release in git. In the tag message editor, delete the generated comments at bottom, leave the first line blank (to omit the release "title" in github), put ### Notable changes on the second line, then copy and paste this version's changelog contents below it.

   git tag -a v$ver --cleanup=verbatim
   git push && git push --tags
   

8. Click here to draft a new release on GitHub. Enter vX.Y in the Tag version box. Leave Release title empty. Copy ### Notable changes and the changelog contents into the description text box.

9. Upload to pypi.org!

   twine upload dist/dag_json-$ver.tar.gz dist/dag_json-$ver-py3-none-any.whl