Skip to content

Ankvik-Tech-Labs/mantaray-py

Repository files navigation

mantaray py

Mantaray data structure in Python

Feature Value
Technology Python Hatch project GitHub Actions Pytest
Type Checking Ruff Checked with mypy
CI/CD Release Tests Labeler pre-commit codecov
Docs Docs
Package PyPI - Version PyPI - Python Version PyPI - License
Meta GitHub license GitHub last commit GitHub commit activity GitHub top language

Description

With this package you can manipulate and interpret mantaray data via MantarayNode and MantarayFork abstractions.

Installation

  • Install using pip
pip install mantaray_py

Usage

Construct Mantaray

from mantaray_py import MantarayNode, MantarayFork, init_manifest_node, gen_32_bytes

node = init_manifest_node()
address1 = gen_32_bytes()
address2 = gen_32_bytes()
address3 = gen_32_bytes()
address4 = gen_32_bytes()
address5 = gen_32_bytes()
address6 = gen_32_bytes()

path1 = "path1/valami/elso".encode()
path2 = "path1/valami/masodik".encode()
path3 = "path1/valami/masodik.ext".encode()
path4 = "path1/valami".encode()
path5 = "path2".encode()
path6 = "path3/haha".encode()

node.add_fork(path1, address1, { "vmi": "elso" })
node.add_fork(path2, address2)
node.add_fork(path3, address3)
node.add_fork(path4, address4, {"vmi": "negy"})
node.add_fork(path5, address5)
node.add_fork(path6, address6, {"vmi": "haha"})
node.remove_path(path3)

print(node)

Mantaray Storage Operations

from mantaray_py import MantarayNode

node = MantarayNode()
"""
here `reference` parameter is a `Reference` type which can be a 32 or 64 of bytes
and `load_function` is a [load_function: (address: bytes): bytes] typed function
that returns the serialised raw data of a MantarayNode of the given reference. See tests/integration/test_int.py file for reference.
"""
node.load(load_function, reference)

# Manipulate `node` object then save it again
# (...)

# save into the storage with a storage handler [save_function: (data: bytes): Reference]
# See tests/integration/test_int.py file for reference.
reference = node.save(save_function)
How It Works

node binary format

The following describes the format of a node binary format.

┌────────────────────────────────┐
│    obfuscationKey <32 byte>    │
├────────────────────────────────┤
│ hash("mantaray:0.1") <31 byte> │
├────────────────────────────────┤
│     refBytesSize <1 byte>      │
├────────────────────────────────┤
│       entry <32/64 byte>       │
├────────────────────────────────┤
│   forksIndexBytes <32 byte>    │
├────────────────────────────────┤
│ ┌────────────────────────────┐ │
│ │           Fork 1           │ │
│ ├────────────────────────────┤ │
│ │            ...             │ │
│ ├────────────────────────────┤ │
│ │           Fork N           │ │
│ └────────────────────────────┘ │
└────────────────────────────────┘

Fork

┌───────────────────┬───────────────────────┬──────────────────┐
│ nodeType <1 byte> │ prefixLength <1 byte> │ prefix <30 byte> │
├───────────────────┴───────────────────────┴──────────────────┤
│                    reference <32/64 bytes>                   │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Fork with metadata

┌───────────────────┬───────────────────────┬──────────────────┐
│ nodeType <1 byte> │ prefixLength <1 byte> │ prefix <30 byte> │
├───────────────────┴───────────────────────┴──────────────────┤
│                    reference <32/64 bytes>                   │
│                                                              │
├─────────────────────────────┬────────────────────────────────┤
│ metadataBytesSize <2 bytes> │     metadataBytes <varlen>     │
├─────────────────────────────┘                                │
│                                                              │
└──────────────────────────────────────────────────────────────┘

Documentation: https://Ankvik-Tech-Labs.github.io/mantaray-py/

Source Code: https://github.com/Ankvik-Tech-Labs/mantaray-py


Development

Development

Setup environment

We use Hatch to manage the development environment and production build. Ensure it's installed on your system.

Run unit tests

You can run all the tests with:

hatch run test:test

Format the code

Execute the following command to apply linting and check typing:

hatch run lint:lint-check

Publish a new version

You can bump the version, create a commit and associated tag with one command:

hatch version patch
hatch version minor
hatch version major

Your default Git text editor will open so you can add information about the release.

When you push the tag on GitHub, the workflow will automatically publish it on PyPi and a GitHub release will be created as draft.

Serve the documentation

You can serve the Mkdocs documentation with:

hatch run docs:docs-serve

It'll automatically watch for changes in your code.

License

This project is licensed under the terms of the BSD 3-Clause License license.